Offline machines (air-gap)

Some machines must never reach the Internet: an industrial network, the information system of a critical infrastructure operator, a hospital’s medical equipment. The TechWatchAlert agent runs there in offline mode: it collects on site, without any network access, and you transfer its files by hand (USB drive, transfer station, data diode). TechWatchAlert receives them as if they came from the online agent: inventory, software monitored in the stack, missing updates, compliance.

Note

Offline mode is part of the agent (version 1.4.0 or later): it is available on the same plans, within the same machine limit. An offline machine counts as a machine with an agent.

How it works

• No connection. On the machine, the agent never calls TechWatchAlert and installs no service: you run its commands when you decide to.
• Encrypted, signed collection. Each collection is encrypted for your organisation’s key (X25519, HKDF-SHA256, ChaCha20-Poly1305): only TechWatchAlert can read it, not the transfer medium nor the relay. It is signed with the agent key, created on the machine at enrolment, time-stamped and numbered: a collection that is altered, replayed or intended for another organisation is refused.
• Signed catalogue. The compliance rules come down in a file signed by TechWatchAlert; the agent checks it before every audit and refuses a catalogue older than the one in place.
• Nothing else comes down. No remote action (installing updates, script, restart) is sent to an offline machine: deployments and actions skip it, with the reason “offline machines”.

Setting up

1. In Fleet › Agents, Offline view, a project administrator downloads an enrolment file: a name, a validity period (90 days by default), a maximum number of uses, and optionally a destination group. One file can enrol several machines.

   Caution

   The enrolment file contains an enrolment token: transfer it as a secret and delete it after use. It is issued only once; the token appears in the Tokens view, where it can be revoked. Revoking a token does not stop machines already enrolled.

2. If you track compliance, also download the compliance catalogue (same view): the rules for your level, for every system. It is valid for one year; download a new one after changing the compliance settings.

3. Copy the agent (Install view, Download the agent) and both files to the machine. As administrator (Windows) or with sudo (Linux, macOS), import the enrolment file, giving the fingerprint shown in the console:

   Linux and macOS

   sudo techwatchalert-agent hors-ligne enroler --fichier enrolement.twa --empreinte <fingerprint>
   sudo techwatchalert-agent hors-ligne catalogue --fichier catalogue.twa

   Windows

   techwatchalert-agent.exe hors-ligne enroler --fichier enrolement.twa --empreinte <fingerprint>
   techwatchalert-agent.exe hors-ligne catalogue --fichier catalogue.twa

   The agent refuses a file whose fingerprint does not match: this is what guarantees that collections will be encrypted for your organisation and not for a third party.

4. Run a collection, to a USB drive or a transfer folder:

   sudo techwatchalert-agent hors-ligne collecter --sortie /media/usb/

   The agent writes a .twa file (full inventory, missing updates, compliance audit) and never overwrites an existing file. With an internal mirror of the package repositories, --actualiser refreshes their metadata first.

5. In Fleet › Agents › Offline, Import collections: choose the file. TechWatchAlert tells you, for each collection, whether it was imported or why it was refused. The machine appears in the fleet with the Offline state and the date of its last import.

Repeat steps 4 and 5 at the pace that suits you (weekly, monthly). A collection older than 30 days is refused: it would describe a machine that has changed since.

Several machines: the relay

A machine in the isolated zone can act as a relay: it gathers the collections of several machines into a single batch, without being able to read them (it does not have the organisation key). It does not need to be enrolled.

techwatchalert-agent hors-ligne regrouper --sortie lot.twa /media/usb/

The relay checks each collection, sets aside unreadable files and duplicates, and orders the batch by machine and number. Import the batch like a collection.

Through the public API

With an API key holding the hors-ligne scope (ticked explicitly: an unrestricted key imports nothing), an automated transfer chain uploads the file as is:

curl -X POST "https://app.techwatchalert.com/api/v1/organizations/$ORG_ID/projects/$PROJECT_ID/hors-ligne/imports?fichier=lot.twa" \
  -H "Authorization: Bearer $TWA_API_KEY" --data-binary @lot.twa

The same scope lets you download the signed catalogue (GET …/hors-ligne/catalogue). Details: API reference.

What you see

• Fleet › Agents: the Offline state, the By file label and the date of the last import. The Offline filter groups these machines with agents that no longer contact TechWatchAlert.
• Machine page: inventory, software, vulnerabilities, missing updates and compliance, dated from the collection; the history records each import.
• Monitoring health: an offline machine is not counted as a silent agent as long as it is imported regularly; it becomes one after 35 days without an import.
• Import history (Offline view): each imported file, by whom, through the interface or the API, and what happened to each collection.

Why a collection is refused

Reason	What to do
Collection already imported, or older than the latest one	Nothing: the most recent collection is already there.
Collection too old	Collect again on the machine.
Other project or other organisation	Import the file into the right project.
Encrypted for another key	Enrol the machine again with a recent enrolment file.
Invalid signature, decryption failed	The file was altered during transfer: collect again.
Token unknown, expired, revoked or used up	First collection of a machine, or reinstalled machine: generate a new enrolment file and import it again on the machine.
Agent revoked	Enrol the machine again with --nouvelle-cle.
Machine limit reached	Free a slot or move to a higher plan.

On the machine

• techwatchalert-agent hors-ligne etat: project, fingerprint, catalogue in place, last collection and its number.
• techwatchalert-agent hors-ligne enroler --fichier … --nouvelle-cle: new agent key (cloned machine, compromised key); the next collection requires a valid token.
• techwatchalert-agent hors-ligne desenroler: erases the agent key, the token, the catalogue and the state. The machine stays in the fleet until it is revoked.

The agent key and the token are stored out of reach of non-administrator users, like the secret of the online agent.

Limits

• Updates are deployed by your usual means inside the isolated zone; TechWatchAlert tells you which ones are missing and on which machines.
• The agent is updated by hand (new binary).
• The compliance profile of an offline machine (workstation or server) follows its system (Windows Server, Windows workstation, macOS) and, for Linux, the default profile of the compliance settings.

Agent and endpoint managementThe online agent: installation, updates, deployments.