Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Method

QuarantineDevice

ModuleSecurity
LibrarySecurity
Action


Excerpt
Attempts to force the device to only communicate using Tachyon.


Warning

Ensure you understand the impact of using the Quarantine feature.

  • Routing tables will be modified. These can be reset by disabling and re-enabling the adapter, or by restarting the machine. Doing so will break quarantine until the next quarantine enforcement period.
  • The hosts file will be modified whilst the device is in quarantine.
  • Agent communications will be limited to IPv4, and only communication with the switch Switch servers and the background channel servers , Background Channel servers, and any designated additional IP addresses will be allowed.
  • IPv6 will be disabled for all adapters.
  • Changes made to routing tables, the hosts file, or IPv6 bindings during quarantine will be lost, as the agent will attempt to revert modifications it makes to a pre-quarantine state.
Warning
The quarantine methods are not suitable for use from TIMS (Tachyon Instruction Management Studio), mainly because of what they do (cut off the device from most connections) but also because no Tachyon Switch is involved with TIMS. If you must use this method in TIMS (which is not recommended) then you will need to give a true value to the Force parameter.


Parameters

(none)

AddedIpAddresses (string; optional, default empty): A comma-separated list of IPv4 addresses. For remediation when quarantined, allow connections from these devices as well as the Tachyon Switch and Background Channel host(s).

Force (boolean; optional, default false): Once a device has been quarantined, only Tachyon can take it out of quarantine because the device is isolated from everything else. This requires that at least 1 Switch and at least 1 Background Channel must be resolvable to an IP address, otherwise a quarantined device would become completely cut off. By default if this condition is not satisfied then the device will not be quarantined because it cannot be restored. However, setting Force to true allows a device to be quarantined regardless, with the risk that it cannot then be unquarantined.

Warning
Using Force risks making un-quarantining using Tachyon impossible.


Note
Prior to v5.1 there were no parameters.


Return values

Status (string): The quarantine status. If the response is a success, this will be Quarantined.

Note
If the device was already in a quarantined state, the action is successful but nothing is returned ("success no content").


Example


Code Block
Security.QuarantineDevice();


Platforms
  • Windows
Notes
  • This is not available on Windows XP.
  • Usually at least one Switch host and at least one Background Channel host must be resolvable to an IP address (so that Tachyon will be able to un-quarantine the device), otherwise the method fails. (New in v5.1.) This can be overridden with the Force parameter.
  • Quarantine requires working persistent storage.
    • If persistent storage is removed or corrupted during quarantine, the agent will be unable to revert to an unmodified state.
  • Communication with the agent can only occur over IPv4.
    • If an IPv4 address cannot be resolved for at least one switch Switch and at least one background channel urlBackground Channel URL, quarantine will not be enforced.
  • The quarantine enforcement interval while the device is not under quarantine can be modified in agent Agent configuration by setting Module.Security.QuarantineEnforcementIntervalSeconds.
  • Upgrading the agent Agent whilst under quarantine is not supported and may cause quarantine to be permanent!
Warning

CRL checks must be set to soft to use the quarantine feature - a CRL expiry can cause the device to become uncontactable. If certificate expiry occurs under Quarantine, the device may become uncontactable. Quarantine will still be in effect in both cases, however.

For more information about using the Quarantine feature please refer to Tachyon 5.1 - Tachyon Quarantine.