> For the complete documentation index, see [llms.txt](https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/findings/agentic-supply-chain-agent-files/findings.md).

# Agent File Findings

The agent-files inventory — the safety score and what drives it, every way to work the list, the file inspection with its risk breakdown and findings, and how to route a risky file for action.

The **Files** view (**Security → Files**) is your inventory of the **AI agent files** in your repositories — the instructions, skills, subagents, hook scripts, and config that steer coding agents. Any of these can quietly redirect an agent, so Heeler inventories every one, scores it for safety, and shows you what it found.

**Each row is one file** (a Skill expands to the files inside it). The page opens **pre-filtered to At Risk files, sorted by Score ascending** — so you land in your triage queue with the riskiest files on top.

{% hint style="info" %}
**Every assistant, not just Claude.** Heeler recognizes agent files across Claude, Cursor, Gemini, Codex, and OpenCode — `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` instructions, the per-assistant layouts (`.claude/skills/*`, `.cursor/agents/*`, `.gemini/settings.json`, …), and MCP config like `.mcp.json`.
{% endhint %}

<figure><img src="https://414480750-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXP3dp2kecwKA2KvYkntz%2Fuploads%2Fgit-blob-e30efb44554bc6f9d1418ed2906ff498f9d8c823%2Fcc-files-list.png?alt=media" alt="The Agent Files list with safety score, assessed intent, and findings per file."><figcaption><p>The Files list — safety score with At Risk marker, assessed intent, and a severity breakdown per file.</p></figcaption></figure>

## The safety score

The number to read first is the **Score** — a **0–100 safety rating where higher is safer**. Anything **below 70 is flagged At Risk**, which is what the "Files — N At Risk" tile counts. Alongside it, **Assessed Intent** gives the judge's one-word verdict:

| Assessed Intent   | Meaning                                                         |
| ----------------- | --------------------------------------------------------------- |
| 🔴 **Malicious**  | The file appears designed to cause harm.                        |
| 🟠 **Suspicious** | The file does something risky or ambiguous, worth a human look. |
| 🟢 **Benign**     | Nothing above a low-severity finding.                           |

{% hint style="info" %}
Intent and score move together: a **Suspicious** verdict caps the score, and **Malicious** caps it lower still, so a file the judge flags always lands At Risk. See [the safety score model](/mrecEO40m5D6bt7Pq5pE/findings/agentic-supply-chain-agent-files.md#the-safety-score) for how the score and verdict combine. There are no Active/Fixed/Deployed tabs here — a file is either at risk or not, as of the last analysis.
{% endhint %}

### What the columns mean

| Column              | What it shows                                                                                                               |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Repository**      | The repo and org.                                                                                                           |
| **Path**            | The file path (links to the code in your SCM at the analyzed commit). A bundle shows an *N FILES* badge and expands inline. |
| **Kind**            | Instructions · Skill · Subagent · Hook Script · Config.                                                                     |
| **Score**           | The 0–100 safety score, with an **At Risk** marker below 70.                                                                |
| **Assessed Intent** | Malicious · Suspicious · Benign.                                                                                            |
| **Findings**        | A severity tally — **C / H / M / L / I** with counts.                                                                       |
| **Last Modified**   | When the file last changed (from SCM history).                                                                              |
| **Ticket**          | An **Assign** affordance, or the linked issue.                                                                              |

A **Summary** column — the judge's one-line "why" — is also available but hidden by default; turn it on from **Manage Columns**.

### Bundles

Skills are usually multi-file — a `SKILL.md` plus scripts and assets. Heeler groups these as a **bundle**: the row shows an *N FILES* badge and an **expand arrow** on the left that reveals its members inline, each with its own **Path**, **Kind**, **Score**, and **Assessed Intent**. The bundle root surfaces the *worst* member's signal, so a risky script tucked inside an otherwise normal-looking skill isn't missed — and any member can be opened in the detail drawer on its own.

<figure><img src="https://414480750-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXP3dp2kecwKA2KvYkntz%2Fuploads%2Fgit-blob-1e3c8e24f4003429c03f35d8b41d36a5ca938b34%2Fcc-files-bundle.png?alt=media" alt="A Skill bundle expanded to show its member files with per-member score and intent."><figcaption><p>A Skill bundle expanded — each member carries its own Score and Assessed Intent.</p></figcaption></figure>

## Working the list

The toolbar is the shared findings toolbar — **Search** (free-text on path and repository), **Export Data** (the **Create Export** modal, with an optional **Recurring Export** frequency), **Refresh**, **Manage Columns** (show/hide/reorder/resize, persisted), and saved-view **Presets** (the bookmark, with Private / Team / Organization visibility). Column headers sort; the list defaults to sorting by **Score**, riskiest first.

### Filtering

Pinned by default: **Repository**, **Assessed Intent**, and an **At Risk** toggle (on by default — clear it to see the full inventory). **All Filters** opens the rest:

| Filter                              | Options                                                                                                                                                                                                                                    |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Assessed Intent**                 | Malicious · Suspicious · Benign                                                                                                                                                                                                            |
| **At Risk**                         | on / off (score below 70)                                                                                                                                                                                                                  |
| **Kind**                            | Config · Hook Script · Instructions · Skill · Subagent                                                                                                                                                                                     |
| **Analysis**                        | Complete · Pending · Skipped                                                                                                                                                                                                               |
| **Confidence**                      | High · Medium · Low                                                                                                                                                                                                                        |
| **Finding Severity**                | Critical · High · Medium · Low · Info                                                                                                                                                                                                      |
| **Repository / Application / Team** | Scope your estate.                                                                                                                                                                                                                         |
| **Has Overrides**                   | on / off — the files whose score has been adjusted by an accepted finding or verdict. See [Overriding what the review got wrong](/mrecEO40m5D6bt7Pq5pE/findings/agentic-supply-chain-agent-files.md#overriding-what-the-review-got-wrong). |

<figure><img src="https://414480750-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXP3dp2kecwKA2KvYkntz%2Fuploads%2Fgit-blob-2f1cfa6054c7ec3101f8f3901d6d0e9dd5389aa2%2Fcc-files-allfilters.png?alt=media" alt="The Agent Files All Filters registry."><figcaption><p>All Filters — including Analysis status, Confidence, Finding Severity, and Kind.</p></figcaption></figure>

{% hint style="info" %}
When **Analysis** is anything other than *Complete*, the score and verdict reflect **partial information**. A file can also be **skipped** (for example, a binary or an oversized file) — a skipped file shows a skip-reason badge and a **–** in place of a score and verdict.
{% endhint %}

## Inspecting a file

Click a file's row to open its detail drawer. The **▲ / ▼** arrows in the header step to the previous or next file in the current filtered, sorted list without closing the drawer.

<figure><img src="https://414480750-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXP3dp2kecwKA2KvYkntz%2Fuploads%2Fgit-blob-012f947ec43ef388638b185a7fd54db3016b8fc1%2Fcc-files-detail.png?alt=media" alt="The file detail drawer: scoring verdict and the Static/LLM/External risk breakdown."><figcaption><p>The file detail — the verdict, a plain-language summary, and the Static / LLM / External breakdown behind the score.</p></figcaption></figure>

The drawer has three sections:

* **File Details** — repository, kind, and last-modified.
* **Scoring** — the **Score** (with At Risk), **Assessed Intent**, **Confidence**, the **Analysis** status, and a plain-language **Summary** of *why* the file is risky. When a file **invokes another file** — a skill or instruction that runs a script — the Scoring section also shows a binding row (e.g. *"Agent may run"* / *"Auto-runs `<target>`"*) with the target linked and its own score — the mechanism by which a clean-looking file inherits risk from something it triggers.
* **Score breakdown** — the three factors behind the score, each with its finding count:

  * **Static Risk** — pattern and structure analysis of the file.
  * **LLM Risk** — a model's read of the file's *intent* (the injected-instruction, deception, and manipulation risks a regex can't catch).
  * **External Risk** — the risk of the external hosts and resources the file reaches out to.

  The three factors roll up into the score — the more findings, and the more severe, the lower the score — and the assessed intent can cap it further (a Suspicious or Malicious verdict pulls it into the At Risk band). See [the safety score model](/mrecEO40m5D6bt7Pq5pE/findings/agentic-supply-chain-agent-files.md#the-safety-score).

### External hosts

When a file references outbound systems, the drawer lists each **external host** with its reputation tier — **developer infrastructure**, **unrecognized host**, or **high-risk host**. For a host that's expected and safe, **Add to allowlist** approves the domain, which does two things:

* The host drops to the trusted developer-infrastructure tier, so it stops contributing to External Risk on the next rescore.
* Its **External Reference** findings are hidden from the file detail, from guardrail evaluation, from violation lists, and from the MCP tools.

Every other finding on the file is untouched. Approved domains are kept centrally on [Trusted Domains](/mrecEO40m5D6bt7Pq5pE/administer-and-monitor/program-policy/trusted-domains.md), where you can also remove one — the findings come back without a rescan.

### Findings

Below the breakdown, the findings are grouped into **LLM Findings**, **Static Findings**, and **External References**. Each shows a severity badge, the finding type, a location or target (a file inside a skill, or an external host/IP), a description, and a **snippet of the offending content** — the exact injected instruction or encoded payload. An **External Reference** finding adds detail specific to outbound calls: the **trigger** (e.g. *Auto-runs on `<event>`*), the target it reaches, the host's reputation tier, and how many points it **adds** to External Risk. Clicking an invoked target or an external reference opens *that* file's drawer, with a **Back** button to return.

<figure><img src="https://414480750-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXP3dp2kecwKA2KvYkntz%2Fuploads%2Fgit-blob-88499709bd83678e488a3f35a203fbab75e3bb26%2Fcc-files-finding.png?alt=media" alt="A finding with its severity, type, and offending code snippet."><figcaption><p>Each finding shows the offending content — here a deception finding instructing the agent to hide its edits.</p></figcaption></figure>

Each finding is one of two kinds — a deterministic **Static finding** or a contextual **LLM finding** — plus **External Reference** findings for outbound systems. For the full catalog of finding types and what each one flags, see [Agent Files → How files are analyzed](/mrecEO40m5D6bt7Pq5pE/findings/agentic-supply-chain-agent-files.md#how-files-are-analyzed).

## Routing a file for action

To hand a risky file off, use the row **⋯** actions — **Push to Jira**, **Push to Linear**, or **Push to GitHub** (each appears once its provider connection is configured, and flips to **Unlink from&#x20;*****X*** once a ticket of that provider is linked). Each row also has **View Details**, and the drawer itself carries the same ticket actions in its header. Skill rows expand inline to the files they contain.

{% hint style="info" %}
Agent files carry no SLO — a file's At-Risk status follows directly from its score, and there is no remediation deadline on it. To lower an assessed risk, [override a finding or the file's verdict](/mrecEO40m5D6bt7Pq5pE/findings/agentic-supply-chain-agent-files.md#overriding-what-the-review-got-wrong) from the detail drawer, or approve the external domain it references (above). Everything else is resolved by fixing or removing the file.
{% endhint %}

## Related

* [Agent Files concept](/mrecEO40m5D6bt7Pq5pE/findings/agentic-supply-chain-agent-files.md) — the safety score, the risk floor, and the analysis passes in depth.
* [Agent Files API](/mrecEO40m5D6bt7Pq5pE/reference/agent-files-api.md) — scan a file or bundle synchronously for CI gating.
* [Secure AI Coding Agents](/mrecEO40m5D6bt7Pq5pE/solutions-and-use-cases/secure-your-ai-coding-agents.md) — discovering, scoring, and governing agent artifacts end to end.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/findings/agentic-supply-chain-agent-files/findings.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.