Skip to content

README.en.md

Latest commit

 

History

History
95 lines (68 loc) · 4.55 KB

README.en.md

File metadata and controls

95 lines (68 loc) · 4.55 KB
Raw

Agent CLI Scope Guard: Audit Global AI Agent Routing and Credential Scope

CI License: MIT

中文 | Documentation | Use cases

Agent CLI Scope Guard is a read-only AI agent CLI security auditor. It detects hidden global Skill routing, cross-host Skill propagation, ambient credential inheritance, bridge environment snapshots, and over-broad execution permissions without collecting secret values.

Use it to answer questions such as:

  • Why did Codex delegate a normal development task to Coze CLI?
  • Does one global Agent Skill affect Codex, Trae, or several coding agents?
  • Can an unrelated child agent inherit API keys from the user environment?
  • Can a package upgrade silently reinstall a routing Skill?
  • Why did parallel agents create duplicate remote projects, drafts, or deployments?

Built-in checks currently cover common Windows and Linux layouts under .agents, .codex, .trae, and .coze. The detection model can be extended to other AI coding agents and vendor CLIs.

Common use cases

Use case Signal Outcome
CLI install or upgrade review A package may add global Skills or lifecycle hooks Before/after configuration baseline
Unexpected platform delegation The user did not name a vendor, but the task moved there Broad routing rule and source path
Cross-agent behavior drift Several agent hosts start behaving the same way Shared pool, symlink, or Junction evidence
Credential scope incident A child agent can see unrelated service credentials Sensitive variable names, snapshots, and ACL findings
Duplicate external writes Retries or parallel writers create duplicate resources Idempotency and single-writer controls
Developer workstation review Full access, no approval, and many trusted projects persist Local trust and permission inventory
DevSecOps image gate A standard image must reject unsafe Agent settings JSON report and severity exit code
Skill author pre-release check A new trigger may be implicit or globally over-broad Routing-boundary review

See detailed use cases for commands and acceptance criteria.

Quick start

Python 3.11 or newer is required. There are no third-party runtime dependencies.

git clone https://github.com/xiaoqi-AI/agent-cli-scope-guard.git
cd agent-cli-scope-guard
python -m pip install -e .
agent-scope-guard

Emit JSON and return exit code 2 when a high-severity finding exists:

agent-scope-guard --json --fail-on high

The default command writes nothing. A report file is created only when --output is explicitly supplied.

What it detects

  • Implicit or mandatory routing in user-level SKILL.md files
  • One physical Skill shared across several agent hosts
  • Package lifecycle scripts that install or resync Agent Skills
  • Sensitive process and Windows user environment variable names
  • Bridge snapshots containing credential field names
  • Broad local read access on credential-bearing files
  • danger-full-access, no-approval execution, and large trusted-project sets
  • Global hooks, rules, requirements, and disabled delete confirmation

Natural-language routing checks are heuristic and require human review. A finding does not by itself prove malicious behavior, remote exfiltration, or a confirmed vulnerability.

Safety guarantees

  • Secret values are never collected or emitted.
  • Local home paths are rendered as ~/....
  • The auditor does not remove Skills, stop processes, change ACLs, revoke tokens, publish, or deploy.
  • Local exposure is reported separately from confirmed remote transmission.

Documentation

Development

python -m unittest discover -s tests -v
agent-scope-guard --help

Contributions are welcome. Every detector must be read-only by default, avoid secret values, state its evidence boundary, document likely false positives, and include a synthetic test.

License

MIT