TL;DR: AP-003 Repository Recon is a coding-agent security pattern where an AI agent quietly builds a working map of a repository before it takes a higher-impact action. A request like "fix this flaky test" can lead the agent to read tests, package manifests, repo instructions, CI workflows, deployment configuration, infrastructure files, and secret references. Each read may be normal. The risk is the sequence: the agent accumulates a Repository Mental Model, and later commands, edits, network calls, or approval prompts should be judged with that accumulated context. Defending against AP-003 requires runtime security that goes deeper than prompt text and longer than a single tool call.
AI coding agents do not begin by editing blindly. They orient. They inspect the failing test, search nearby files, read the README, check the package manifest, discover the test command, open repository instructions, and often inspect CI workflows to understand why local behavior differs from automated checks. That is not a bug. It is a large part of why coding agents are useful.
But the same behavior creates a security problem that traditional controls do not describe very well. By the time the first edit happens, the agent may already know where tests run, which CI jobs gate merges, which branches trigger deploy previews, which scripts publish artifacts, where staging credentials are referenced, and which infrastructure files connect the repository to production-like systems. That knowledge is not passive. It shapes the next command, the next edit, and the next approval request.
In one sentence: Repository Recon is the moment AI coding agent security stops being about whether a single file read is allowed and starts being about what the agent now knows, how that knowledge was accumulated, and whether the next action uses that knowledge to cross an operational boundary.
The risk is not one read. It is the sequence. Repository Recon turns ordinary repository exploration into an operational map that should change how later actions are evaluated.
Attack card
| Attack ID | AP-003 |
| Name | Repository Recon |
| Pattern | A coding agent accumulates repository and operational context through normal reads, then uses that context to choose or justify a later higher-impact action. |
| Primary condition | AI coding agents with access to source code, tests, dependency manifests, CI workflows, repository instructions, deployment files, infrastructure configuration, or secret references. |
| Common triggers | Debugging failures, test repair, dependency updates, build errors, CI failures, unfamiliar repositories, agent memory files, and project-specific rule files. |
| Security impact | The agent learns release paths, credential locations, deployment assumptions, protected workflow structure, package publishing routes, and internal service dependencies before later operations. |
| Key distinction | The individual reads may be allowed and expected. The security-relevant event is the accumulated repository model and how it influences later actions. |
| Detection challenge | File-level controls see ordinary reads. Command-level controls see ordinary commands. The risk appears only when runtime security connects the exploration history to a later action. |
Reconnaissance comes before exploitation
Experienced attackers rarely start with the destructive command. They learn first. They identify where sensitive systems are, which identities matter, how workflows connect, and which small changes create downstream leverage. Coding agents are not attackers by default, but they often follow a structurally similar pattern because software engineering itself rewards context gathering.
Consider a simple request: "Fix the flaky integration test." The agent opens the test file and nearby implementation. It checks the package manifest to find test scripts. It reads CI configuration to understand why the test fails only in automation. It opens README instructions for integration tests, finds that staging services are required, and sees references to environment variables used by the test harness. While solving the task, the agent has learned more than the test failure. It has learned how the repository is built, tested, wired to staging, and trusted.
None of those reads need to be malicious. In fact, blocking them aggressively would make the agent less useful. The security issue begins when the next action arrives with the Repository Mental Model behind it. A small workflow edit, a package command, a credential request, a network call, or a deployment configuration change should no longer be evaluated as if it appeared from nowhere.
What is a Repository Mental Model?
A Repository Mental Model is the operational map an AI coding agent builds while exploring a codebase. It can include source layout, test strategy, package managers, dependency registries, build commands, CI gates, deployment paths, artifact names, infrastructure files, organization-specific instructions, and secret references. Modern coding agents are designed to construct this model because repository-aware agents are much better at completing real engineering tasks.
This model often comes from multiple layers. It comes from source files and test files. It comes from dependency manifests such as package.json, pyproject.toml, go.mod, or lockfiles. It comes from CI workflows, deployment scripts, Dockerfiles, Terraform files, Kubernetes manifests, policy files, and README instructions. It also comes from agent-specific context files: Claude Code uses CLAUDE.md for persistent project guidance, Codex recognizes AGENTS.md as repository guidance, and Cursor rules can encode project-specific workflows and architectural conventions.
The important point is not which agent reads which exact file. The important point is that repository context has become part of the agent's runtime state. Once that state includes operational context, later actions need contextual evaluation.
Why action-level policies miss Repository Recon
Action-level security asks whether a specific operation should be allowed. Can the agent read this file? Can it run this shell command? Can it edit this workflow? Can it access this URL? Those questions are necessary for writes, installs, network access, shell execution, credential use, and deployment operations. They are not enough for Repository Recon because the risky unit is not a single operation.
Reading a README is normal. Reading a package manifest is normal. Reading a CI workflow may be normal. Reading deployment configuration may be normal for many tasks. Even reading a file that references secret names may be legitimate if the agent is debugging configuration. If every one of those reads is judged independently, the log looks quiet. The agent has not modified anything. It has not exfiltrated data. It has not run a dangerous command. Yet from a workflow perspective, it has learned the repository's operational shape.
For example, a user asks an agent to "update lint config." The agent reads the linter config, package scripts, CI workflow, deployment notes, and cloud build file to ensure the change will pass automation. No individual read is surprising. But now the agent knows which branch patterns trigger protected jobs, where artifacts are produced, and which environment variables are referenced by release workflows. A later edit to one CI line or one package command has a different security meaning after that exploration.
Repository Recon as a workflow-level pattern
AP-003 is a workflow-level pattern. It usually begins with a legitimate engineering task. The agent loads context, discovers build and test conventions, sees CI and deployment paths, learns secret-reference locations, identifies artifact names, maps package registries, and notices internal service dependencies. Later, a higher-impact action appears small because the agent has already built the map that makes it precise.
The later action may not be dramatic. It might be one line in a CI workflow, one package-manager command, one deploy-config edit, one artifact publish step, one credential request, or one network call to a staging system. The Repository Mental Model does not need to be perfect to matter. Partial knowledge of pressure points is often enough to change risk.
This is different from prompt injection, where hostile instructions steer the agent. It is different from hallucination, where the agent invents a false dependency or API. It is different from simple file access control, where the question is whether a file is allowed. AP-003 is about the relationship between what the agent has learned and what it tries to do next.
Engineering implications
The answer is not to stop agents from learning repositories. Blind agents are worse agents. The useful security question is: which repository knowledge should change runtime posture? Reading source and tests may be ordinary orientation. Reading deployment workflows, infrastructure manifests, release scripts, package-publishing configuration, and secret references may still be allowed, but it should raise the sensitivity of later operations that touch shell commands, package managers, workflow files, network calls, credentials, or release paths.
Approvals should carry history. A prompt that asks "Allow command: npm publish?" is less useful than one that explains the agent previously inspected package metadata, registry configuration, CI release jobs, and secret references while working on a lint change. The command is not floating in isolation. It is the latest point in a trajectory.
Likewise, alerts should distinguish between local code understanding and operational recon. Reading a test and its implementation is normal for a test fix. Reading deployment manifests and credential references during a UI styling task is different. A runtime system should preserve that difference without making useful repository exploration impossible.
Detection and mitigation
Detection should focus on knowledge accumulation, not isolated reads. A practical approach is to classify repository reads by category: orientation, dependency, build, test, deployment, infrastructure, credential reference, release, and organization policy. The runtime should notice when an agent crosses from local code context into operational context, then carry that signal forward into later decisions.
Mitigation should be proportional. A README read should not create an alert by itself. A sequence that includes CI workflows, deployment manifests, secret-reference files, and package-registry configuration should increase scrutiny for later shell commands, package installs, workflow edits, network calls, credential use, and publishing activity. A read-only sequence can change the risk of a later write.
This is what trajectory-aware policy means in practice. The system does not only ask whether a file read is allowed or whether a command is syntactically dangerous. It asks what the agent has learned, whether that knowledge is operationally sensitive, and whether the next action uses that knowledge to cross a trust boundary.
Short answer for security teams: Detect AP-003 by tracking repository context categories over time, not by flagging every repository read. Mitigate it by carrying those context categories into later approval, blocking, scoping, and audit decisions.
Where Gensee Crate fits
Gensee Crate is built for long-horizon runtime visibility and enforcement around AI coding agents. For AP-003, the key differentiator is that Crate can connect the human request, agent task, repository reads, agent tool calls, shell activity, file changes, package operations, approvals, and system events into one runtime trajectory. That deeper and longer view is exactly what Repository Recon requires.
The goal is not to block agents from understanding code. The goal is to recognize when accumulated context changes the meaning of the next action. If an agent has learned deployment paths, secret-reference locations, or release-gate structure, runtime enforcement should evaluate later operations with that history attached. A code edit, shell command, package operation, or approval request should not be treated as context-free.
In practice, this means Crate can support useful exploration while making operational knowledge visible. It can preserve lineage and provenance across requests and sessions, expose offline event tracking in a dashboard or CLI, and enforce risky operations in the coding-agent chat interface when the trajectory no longer matches the user's authorized task.
Questions for engineering and security teams
Which repository reads count as ordinary orientation, and which count as operational context? Can your agent see CI workflows, release scripts, infrastructure files, deployment manifests, or secret-reference locations? When an approval prompt appears, does it explain what the agent has already learned, or only the command it wants to run?
Can your logs reconstruct why an agent edited a workflow file, invoked a package manager, touched a deployment path, or asked for a credential? Do your controls remember repository exploration across multiple turns and sessions? If the answer is no, the organization may have file logs and command logs, but not agent-runtime security.
Frequently asked questions
What is AP-003 Repository Recon?
AP-003 Repository Recon is a coding-agent security pattern where an AI agent builds a working map of a repository before acting. It reads source files, tests, manifests, CI workflows, deployment configuration, infrastructure files, and secret references, then uses that accumulated context to choose later actions.
What is a Repository Mental Model?
A Repository Mental Model is the operational map an AI coding agent forms from repository exploration. It can include how code is organized, how tests run, which packages and registries are used, how CI gates releases, where deployments happen, and where credentials are referenced.
Why do action-level policies miss Repository Recon?
Action-level policies usually evaluate one file read, command, or tool call at a time. Repository Recon is risky because the sequence of normal reads changes the meaning of a later edit, shell command, network request, or approval prompt.
Is Repository Recon always malicious?
No. Repository Recon often looks like useful software engineering. Coding agents need repository context to work well. The security issue is that operational knowledge, such as deployment paths or secret references, should change the runtime posture of later actions.
How does Gensee Crate help with Repository Recon?
Gensee Crate connects the human request, agent task, repository reads, tool calls, shell activity, file changes, package operations, and approvals into one runtime trajectory. This lets enforcement judge later operations with the context the agent has already accumulated.
Sources
This post references Anthropic's Claude Code memory documentation, OpenAI Codex's AGENTS.md discovery implementation, Cursor's rules documentation, and the open-source Gensee Crate repository.