Skip to main content

1E SDK

Security.QuarantineDevice

Method

QuarantineDevice

Module

Security

Library

Security

Action

Attempts to force the device to only communicate using Tachyon.

Warning

Ensure you understand the impact of using the Quarantine feature.

The quarantine methods are not suitable for use from Tachyon Instruction Management Studio (TIMS), 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.

For more information about using the Quarantine feature, please refer to Tachyon Explorer - Tachyon Quarantine.1E Quarantine

  • 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 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.

Parameters

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.

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

Security.QuarantineDevice();

Platforms

  • Windows

Notes

  • 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.

    Warning

    The Background Channel URL (including the port number) is not checked, so it is possible that a subsequent security remediation instruction that uses it will not work. However, a simple instruction to just unquarantine the device will work fine because it would not need the Background Channel.

  • Quarantine requires the Agent's 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 and at least one Background Channel URL, quarantine will not be enforced.

  • The quarantine enforcement interval while the device is not under quarantine can be modified in Agent configuration by setting Module.Security.QuarantineEnforcementIntervalSeconds.

  • Upgrading the 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 Quarantine.1E Quarantine

In this section: