> For the complete documentation index, see [llms.txt](https://docs.stepsecurity.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stepsecurity.io/packages/secure-registry/policy-evaluations.md).
# Policy Evaluations
The **Policy Evaluations** tab is an audit log of every package request (npm or PyPI) that flowed through Secure Registry, with the evaluation result for each enabled control. Use it to confirm that requests are flowing through Secure Registry, to investigate why a specific install was blocked or modified, and to trace a request back to the developer machine or CI run that made it.
### Filters
Filters at the top of the page let you narrow the log:
* **Status**: filter by evaluation result (Allowed, Modified, Blocked).
* **Ecosystem**: filter by npm or PyPI.
* **Type**: request type (Metadata, Tarball Download).
* **Source**: filter by where the request originated (Developer Machine or GitHub Actions).
* **Package**: exact package name (e.g., `lodash`).
* **Versions**: comma-separated versions (e.g., `4.17.21,4.17.20`).
* **Identifier**: filter by a specific source identifier.
* **Date range**: narrow to a specific time window.
### Statuses
| Status | Meaning |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Allowed** | The request matched no blocking controls and was served as-is. |
| **Modified** | One or more controls filtered the response. Most commonly, Cooldown removed one or more recent versions before returning metadata, so the client sees only versions older than the cooldown window. |
| **Blocked** | A control blocked the request. The package version was not served. This is the result when Compromised Packages, Typosquatting Protection, or a Tarball Download inside the cooldown window matches the request. |
| **Skipped** (per-control) | The control was not evaluated for this request, either because it is disabled in the Policy tab or because it is not yet available. |
### Modified vs Blocked example
The difference comes down to which request the control acts on.
When a client installs a package (for example, `npm install axios`), it first requests the package's **metadata**, which lists every published version. Secure Registry filters that response before returning it, removing any versions that are inside the cooldown window or flagged as compromised. Because the response was changed rather than refused, the evaluation is logged as **Modified**. From the client's perspective the filtered versions simply don't exist, so it resolves to the latest safe version and the install proceeds normally.
If a client directly requests a disallowed version (for example, `npm install axios@` where that version is in cooldown or compromised), or downloads its tarball, there is nothing to filter because the request itself targets a disallowed version. Secure Registry refuses to serve it and the evaluation is logged as **Blocked**.
### Request types
* **Metadata**: a request for package metadata (for example, `npm view`, or dependency resolution during install).
* **Tarball Download**: a request for the actual package tarball during install.
### Source attribution
The **Source** and **Source Identifier** columns show where each request originated, so you can trace any evaluation back to the developer machine or CI run that made it. This requires the source identifier to be configured in your client setup; see Setting up source attribution on the Setup Guide. Requests from clients that do not send an identifier still appear in the log but are not attributed to a specific device or workflow run.
| Source | Source Identifier links to |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Developer Machine** | The device page for that machine, filtered to its Device ID. From there you can inspect the device's installed IDE extensions, AI agents, MCP servers, OSS packages, and suspicious files. |
| **GitHub Actions** | The Harden-Runner workflow run that made the request, where you can review its outbound network destinations, file write events, and detections. |
Clicking a **Source Identifier** value opens the linked page, which lets you pivot directly from a blocked or modified install to the full context of the machine or workflow run behind it. For example, if a developer machine triggered a blocked install of a compromised package, you can open its device page to see what else is running on that machine.
**Follow this interactive demo to see how it works in practice:**
{% embed url="" %}
### Per-control breakdown
Click any row to expand the per-control breakdown. For a **Modified** request, the breakdown shows which control modified the response and the reason (for example, "2 version(s) filtered by cooldown period"). For a **Blocked** request, the breakdown shows which control blocked it and why.
---
# 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.stepsecurity.io/packages/secure-registry/policy-evaluations.md?ask=&goal=
```
`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.
