How Takumi Agent works

info

The English user guide is currently in beta preview. Most of the documents have been automatically translated from the Japanese version. Should you find any inaccuracies, please reach out to Flatt Security.

This page describes how Takumi Agent runs Takumi Guard on the Mac: where requests go, what the package installs, the rules behind the design, and how the device works out its state.

Subject to change

The behavior described here is what Takumi Agent does today. Changes are announced in the release notes, except where an urgent security fix requires changing it without notice.

Request flow

The diagram below shows where a request from a tool on the Mac goes.

Components

One package installs three parts: the menu-bar app, which shows the device's state and activates the rest; a macOS system extension, which captures connections to the supported registries; and a background service, which asks Takumi Guard for a verdict and relays the answer.

The background service starts when the Mac boots, before anyone logs in, so protection doesn't depend on a user session.

Design rules

A few rules shape the design:

• Only registry traffic is touched. Every other connection passes through and is never decrypted.
• The device makes no security decisions. Blocklists and policy live in Takumi Guard, so protection stays current without app updates.
• Fail closed. If Guard can't be reached, a captured request is rejected instead of being sent to the public registry.
• A certificate authority per device. To read registry traffic, the agent generates a certificate authority on the Mac. Its private key never leaves the Mac, and it is only used for the supported registries.
• An egress lock. A network filter blocks direct connections to the supported registries, so nothing reaches them without going through Takumi Guard.

The device certificate authority

The device certificate authority is created on the Mac at install, and its private key never leaves it. macOS only trusts it after an administrator's direct approval, so the installer can't do that for you (see Step 5 of the Quickstart). Until then, captured installs fail closed. Tools with their own certificate store read it from the agent's trust bundle (see Developing with Takumi Agent). Uninstalling deletes the key and removes the certificate from the System keychain (see Uninstalling).

How the verdict is worked out

The device works out its own verdict from the state of each health check:

• Capture: the system extension is installed and activated, the network proxy is switched on, and the background service is running and listening.
• Device CA: the device certificate is present, trusted in the System keychain, and not near expiry.
• Egress lock: the network filter is active.
• Capture set: the supported registry hostnames are being captured.
• Credential: the device is enrolled and has a valid Guard credential.
• Runtime trust: the trust bundle is in place, and tools with their own certificate store trust the device certificate. A container that rejects it is a note, not a fault.

The verdict follows these rules:

• Any red health check makes the device Not protected. Otherwise, any amber health check makes it Degraded. Otherwise it is Protected.
• Unconfirmed counts as amber. A health check whose state can't be confirmed counts as amber, because a missing reading is not a pass. A condition this version of the agent doesn't recognize also counts as amber, so it can't turn a whole fleet red on its own, and it can't quietly disappear from the verdict either.
• Off by policy is not a fault. An ecosystem your organization doesn't enforce never changes the verdict.
• Blocked is not bypassed. A container that rejects the device certificate never reaches the registry, so it is a note, not a fault.
• A temporary state can't stay amber forever. A condition that is expected to clear on its own turns red if it doesn't clear. Conditions that wait on a person stay amber.

The console can only ever show a device as worse than its own verdict, never better. Offline, Removed and tamper evidence all take priority over what the device reports (see Device states).

Tamper evidence

If an attacker with root access could disable the system extension and then erase the evidence with one clean check-in, the detection would be useless. So the server keeps the evidence, and a later healthy report doesn't clear it. The device shows Not protected until an administrator acknowledges the evidence.

Acknowledging is the way out of a false positive, without decommissioning and re-enrolling the device. It clears the recorded evidence and nothing else. If the device reports tampering again, the evidence is recorded again with a new First observed time, and the earlier acknowledgement is still shown below it.