Metadata-Version: 2.4
Name: intercept-agent
Version: 0.4.21
Summary: Intercept Developer Posture Agent - collects developer environment data
Requires-Python: >=3.12
Requires-Dist: click>=8.1.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: pyyaml>=6.0.0
Description-Content-Type: text/markdown

# intercept-agent

Developer endpoint agent for the [Intercept](https://hijacksecurity.com)
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`](https://pipx.pypa.io) 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.

```sh
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`](https://docs.astral.sh/uv/) installed, you can skip
the install step entirely -- `uvx` resolves and runs the command in a
disposable environment:

```sh
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):

```sh
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

```sh
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`:

```sh
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](https://hijacksecurity.com) for the full
report schema.

## Uninstall

```sh
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](https://github.com/hijacksecurity/Intercept)
