CLI & CI
Catch risky agent tooling before it ships. The scanner reads your MCP configs, OpenAPI specs, and n8n workflows, scores every action an agent could take, and fails your build on drift or new high-risk capabilities.
The actpass CLI
In this repository the CLI runs from source via npm scripts (tsx packages/cli/src/index.ts):
shell
npm run actpass -- --help # all commands
npm run actpass:scan -- --mcp mcp.json
npm run actpass:policy:test -- owasp-agent| Command | What it does |
|---|---|
init | Create a starter actpass.json + sample actpass.gateway.json (-p/--project sets the name). |
scan | Scan an MCP config (--mcp), OpenAPI spec (--openapi), n8n workflow (--n8n), or single tool manifest (--manifest). --format json|markdown|short, --out <file>. |
diff | Compare a fresh scan against actpass.lock (--baseline) and exit nonzero on drift. |
policy test | Run policy tests in a JSON/YAML fixture file or built-in profile (e.g. owasp-agent). --replay-out writes deterministic replay artifacts. |
report export | Export a trust report (--format markdown|json, --scan, --lock, --out). |
mcp proxy | Run a local MCP proxy aggregating servers under ActPass policy (--config actpass.gateway.json). |
install | Pair this CLI to an ActPass tenant via browser-attested consent (RFC 8628 device flow). |
login | Authorize this laptop as a device (--url, --key apk_...); --register-agent also registers a local coding agent. |
enroll | Print MCP config to wire ActPass into Claude Code and Codex. |
hook | Claude Code PreToolUse hook (--mode monitor|warn|enforce|strict, --rule-of-two, --block-color-mix). |
control | Run the ActPass control MCP server (policy management) on stdio. |
exposure | Lethal-Trifecta / MCP-color exposure report (--agents, --mcp, --format md|json, --baseline for CI gating). With no flags, auto-scans this machine’s Claude/Cursor/VS Code MCP configs. |
wrap | Wrap an MCP server command to enforce ActPass policies (legacy desktop-proxy mode). |
examples
# scan a Claude Desktop / Cursor MCP config
npm run actpass -- scan --mcp ~/.cursor/mcp.json --format markdown
# lock the surface, then gate CI on drift
npm run actpass -- diff --baseline actpass.lock --mcp mcp.json
# test a policy fixture (or the built-in owasp-agent profile)
npm run actpass -- policy test policies/refunds.test.jsonTip:Commit
actpass.lock. It pins the approved hash of every tool your agents can reach. diff then catches rug-pulls the same way a package lockfile catches dependency swaps.GitHub Action
The same scanner, on every pull request. It posts a PR comment with findings and fails the check when new risk appears (source: integrations/github-action).
.github/workflows/actpass.yml
name: ActPass Security Scan
on: [pull_request]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actpass/scan-action@v1
with:
path: . # project root to scan
fail-on: high # critical | high | medium | low
baseline: actpass.lock # drift detection baseline
# narrow the surface if needed:
# mcp-config: agents/mcp.json
# openapi: api/openapi.yaml
# n8n-workflow: flows/support.json| Input | Default | Purpose |
|---|---|---|
path | . | Project root to scan |
fail-on | high | Minimum severity that fails the check |
baseline | actpass.lock | Lockfile for drift detection |
mcp-config / openapi / n8n-workflow / manifest | none | Point at specific configs instead of auto-discovery |
report-format / report-path | markdown / actpass-report.md | Rendered report format and location |
init-lock | true | Bootstrap a missing actpass.lock instead of failing the check |
The action outputs decision (fail | warn | pass), highest-severity, findings-count, and drift-count, and exits non-zero on findings at or above your fail-on threshold, so a tool that quietly gained delete powers blocks the merge instead of surfacing later in a postmortem.