intercept-agent 0.4.28

Intercept Developer Posture Agent - collects developer environment data

intercept-agent

Developer endpoint agent for the Intercept supply chain security platform. Collects metadata about the developer environment (installed tools, IDEs, AI assistants, MCP servers, security posture) and reports it to your Intercept tenant.

Cross-platform: macOS, Linux, Windows. Python 3.12+.

The agent collects metadata only -- names, versions, boolean statuses. It never reads file contents of SSH private keys, credentials, or tokens.

Install

You will receive an enrollment token (starts with hse_) from your Intercept admin. Pick whichever install command works on your machine:

Recommended: pipx (works on every platform, no PATH gymnastics)

pipx is the standard tool for installing Python CLIs. It puts the agent in its own isolated environment and automatically wires up the intercept-agent command on PATH for you.

pipx install intercept-agent
intercept-agent setup --token hse_xxxxxxxxxxxx

If you don't have pipx:

• macOS: brew install pipx && pipx ensurepath
• Linux: python3 -m pip install --user pipx && python3 -m pipx ensurepath
• Windows: py -m pip install --user pipx && py -m pipx ensurepath

Open a new terminal after ensurepath so the updated PATH takes effect.

One-shot: uvx (if you already use uv)

If you have uv installed, you can skip the install step entirely -- uvx resolves and runs the command in a disposable environment:

uvx intercept-agent setup --token hse_xxxxxxxxxxxx

This is the cleanest path if you already use uv for Python projects.

Fallback: pip + python -m posture_agent

If neither pipx nor uv is an option, use pip and invoke the agent as a module. This works regardless of whether the intercept-agent console script ends up on PATH (the common Windows pain point):

pip install intercept-agent
python -m posture_agent setup --token hse_xxxxxxxxxxxx

On macOS / Linux you may need pip3 and python3 instead of pip and python. On Windows, py -m pip install intercept-agent followed by py -m posture_agent setup --token ... works without needing python on PATH at all.

What setup does

intercept-agent setup --token <hse_...> is a one-shot bootstrap:

1. Calls Intercept's enrollment endpoint to exchange the one-time enrollment token for a per-machine API key (hsk_...).
2. Writes ~/.config/intercept/agent.yaml with the API key and the correct API URL for your tenant.
3. Installs the per-platform scheduler so the agent runs every hour:
   • macOS: launchd plist at ~/Library/LaunchAgents/com.hijacksecurity.intercept-agent.plist
   • Linux: systemd user service unit
   • Windows: Task Scheduler entry
4. Runs the first collection immediately so the machine appears in the Intercept UI within a minute.

After setup completes you don't need to do anything else -- the agent reports to your tenant automatically on the configured interval.

Other commands

intercept-agent status         # Show install / scheduler / config status
intercept-agent collect        # Dry-run: print the next report to stdout
intercept-agent collect --report  # Force a report send right now
intercept-agent update         # Upgrade the agent to the latest version on PyPI
intercept-agent uninstall      # Stop the scheduler and remove the plist / service / task
intercept-agent uninstall --purge   # Also remove ~/.config/intercept

All of these work the same way under the python -m posture_agent fallback. For example: python -m posture_agent status.

Re-enrolling on an already-configured machine

If you need to switch tokens, move to a new tenant, or just reset local state, pass --force to setup:

intercept-agent setup --token hse_xxxxxxxxxxxx --force

--force wipes the existing configuration (and any installed scheduler) before re-enrolling. It replaces the older two-command dance (uninstall --purge followed by setup), which was fragile on Windows when the intercept-agent console script wasn't on PATH.

What the agent collects

Per-machine metadata reported to Intercept (no file contents, no secrets):

• Machine: hostname, username, OS, CPU, memory.
• IDEs: VS Code, Cursor, JetBrains family, Xcode, vim, Sublime, Windsurf, Zed, etc. -- name + version only.
• IDE extensions: id + version for installed VS Code / JetBrains plugins.
• AI tools: Claude Code, Cursor, Copilot, ChatGPT Desktop, Codeium, etc. -- as CLIs, extensions, and desktop apps.
• Dev tools: Git, Docker, languages (Node, Python, Go, Rust...), build tools, cloud CLIs.
• Package managers: Homebrew, npm, pip, cargo, etc.
• Security posture: git signing config, SSH keys (algorithm + filename only -- never key contents), SSH agent type, disk encryption state (FileVault / BitLocker / LUKS), OS firewall state, app gatekeeper state, git credential helper.
• MCP servers: which MCP servers each AI tool has configured, plus risk indicators (env-var-named credentials, etc.).

See the Intercept docs for the full report schema.

Uninstall

intercept-agent uninstall --purge    # remove scheduler + config + logs
pipx uninstall intercept-agent       # if installed via pipx
pip uninstall intercept-agent        # if installed via pip

Privacy & security

• Endpoint metadata only. No file contents of keys, credentials, or source code is ever read.
• All data is sent over HTTPS to your tenant's Intercept gateway.
• Authentication uses a per-machine API key (hsk_...) issued during enrollment. The original hse_... enrollment token is one-time use.
• You can revoke a machine's access from the Intercept UI at any time.

Support

If intercept-agent isn't recognized after pipx install, run a fresh terminal (so PATH refreshes). If you're still stuck, the python -m posture_agent setup --token ... fallback works without any PATH configuration -- use that and tell us about the platform you're on so we can fix the install story for the next person.

Source: hijacksecurity/Intercept