Most security reviews are organised around files. Open the agent configuration. Open the MCP configuration. Open the workflow. Open the repository instructions. Check each one for a suspicious line.
That review is necessary. It misses the risk that lives between the lines.
An AI coding agent can read instructions from a repository, run under a permissive policy, discover an MCP server, and use a credentialed write tool. None of those facts has to look catastrophic in isolation. Together they form a path from text in a pull request to an external side effect.
The path is the finding.
A single-file review cannot see the whole boundary
Consider a common setup:
CLAUDE.md repository-controlled instructions
.claude/settings.json pre-approved tools and permissions
mcp.json a GitHub server with write tools
workflow a privileged pull_request_target trigger
environment a GitHub token available to the processEach file answers a different question. CLAUDE.md says what the agent is told to read or do. The settings file says what it can do without asking. The MCP configuration says which external capabilities it can call. The workflow says when the agent runs and which identity it inherits.
The security question is not whether any one of those files contains the word “dangerous.” It is whether untrusted repository content can reach a privileged action without a human boundary.
What the capability graph maps
ship-safe capabilities . reads the configuration that defines an agent's reach and represents it as nodes and edges.
The nodes include:
- repository-controlled instruction files
- runtime permission grants and approval policies
- MCP servers and their tools
- credentials passed to the process
- workflow triggers and privileged jobs
- filesystem, shell, network, and external write capabilities
The edges describe how those nodes connect: which instruction files the runtime ingests, which tools a policy grants, which server receives a credential, and which trigger starts the workflow.
The command then reports combinations that are dangerous together while ordinary apart. Examples include repository instructions reaching an unattended write capability, a wildcard tool approval over a credentialed server, agent write access reaching workflow secrets, and credentials written directly into agent configuration.
Every step cites the file and line where it was observed.
The path matters more than the node
An MCP server that only returns public weather data is not equivalent to the same server running with a deployment token. A write tool that always asks for approval is not equivalent to the same tool under always_allow. A repository instruction is not equivalent to an operator-owned instruction outside the branch being reviewed.
The nodes are not the conclusion. The edges determine what one node can influence.
This is also why a capability review should not flatten everything into a single severity list. “Shell access exists” is a fact. “Repository-controlled instructions can invoke shell access with no approval and a production credential in scope” is a path. The second statement is the one a maintainer can act on.
The output is designed for a fix
The graph does not merely say “review your permissions.” It gives the team a way to break the chain:
1. remove the pre-granted write or execute permission
2. require approval at the side-effect boundary
3. scope the tool allowlist to the agent's actual job
4. remove credentials from processes that do not need them
5. keep repository-controlled instructions out of privileged automation
6. separate untrusted pull-request work from trusted release jobs
The best remediation is often one removed edge, not a rewrite of every node. If an agent needs to read a repository but never to create a pull request, do not grant the write tool and then rely on the prompt to behave. If it needs to call a deployment API, give that action its own approval and a short-lived, scoped identity.
Run it beside the scanner
The capability graph complements audit; it does not replace it.
audit finds risky patterns in application code, agent definitions, MCP configs, CI, secrets, and dependencies. capabilities asks what the configured agent can reach when those files are combined. investigate then records the evidence and verdict behind findings that need a deeper conclusion.
Use the graph locally:
npx ship-safe capabilities .
npx ship-safe capabilities . --json
npx ship-safe capabilities . --env--json is for CI and other tooling. --env includes the operator's own MCP servers, which is useful when the effective capability set lives partly outside the repository. That mode should be treated as sensitive: it describes the environment in which the agent is running.
The actor cannot review its own reach
An AI coding agent can review the files it was asked to review. It cannot be the only authority on what it is allowed to reach, because its own runtime policy and external tools may be outside the repository context it receives.
That is the same reason an author should not be the only reviewer of a security-sensitive change. The question is not whether the agent has good intentions. It is whether a piece of text it can read can influence an action it can take.
The capability graph makes that boundary visible to a human before the agent gets a credential and a tool.
What the graph does not prove
A configured edge is not proof that every run will exercise it. A missing file is not proof that a gateway has no control. An external platform may add an approval boundary the repository cannot see.
The graph is therefore an evidence-backed map of configured reach, not a universal claim about runtime behavior. That limitation is a feature of the output. It tells the reviewer which boundary is visible, which assumption is outside the repository, and where an additional control belongs.
The useful question is simple: if an attacker controls text in this repository, what can that text cause the agent to touch?
Run the graph, read every cited edge, and remove the ones that do not need to exist. The safest agent is not the one with the most reassuring instructions. It is the one whose capabilities are narrow enough that an instruction cannot turn into an incident.
Read the capability documentation, the security model, and the Ship Safe CLI.
Ship Safe is MIT licensed. The capability graph runs locally and reports the files and lines that make each path possible.