> 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/github/malicious-files.md).

# Malicious Files

{% hint style="info" %}
Malicious Files is in beta.
{% endhint %}

**Malicious Files** scans the full history of the repositories in your GitHub organization for files planted by known supply chain attack campaigns, and shows you every file that matches, which branches, pull requests and tags still contain it, and the commit that introduced it.

To open it, select **Malicious Files** in the **GitHub** section of the left navigation. Use the organization selector at the top of each page to choose which GitHub organization to view.

This section contains three pages:

* **Rules**: the detection rules StepSecurity maintains, and the checks each rule runs.
* **Scan Status**: the most recent scan of each repository in the organization.
* **Findings**: every file that matched a rule, where it is, how it got there, and how to respond.

### Why it matters

In several recent supply chain campaigns, attackers who gained write access to a GitHub repository pushed malicious files into it. These files usually land on branches other than the default branch, where maintainers are less likely to notice them. A developer who clones the repository, checks out an affected branch, and opens it in their editor or AI coding agent can run the malware without realizing it, for example through an editor task that runs when a folder opens or an AI agent hook that runs when a session starts.

Because these files can sit on any branch, pull request or tag, reviewing the default branch alone does not find them. Malicious Files checks every version of every file across all of them.

### How it works

* **Rules managed by StepSecurity:** StepSecurity writes and maintains a set of detection rules for files dropped by known campaigns. The rules are enabled by default and apply to every repository automatically, so there is nothing to configure.
* **Full history scan:** StepSecurity checks each repository's full history, across every branch, pull request and tag, against the rules. Scans run incrementally after workflow runs are analyzed.
* **Findings:** when a file matches a rule, StepSecurity records a finding. One finding is one file path matched by one rule, across every version of that file.
* **Rule updates:** StepSecurity adds and revises rules as new campaigns are identified. New and revised rules apply to changes scanned after the update, and each finding shows the rule revision that produced it.

{% hint style="info" %}
Malicious Files for GitHub scans the repositories in your GitHub organization. To find the same kinds of planted files on developer machines, see [Malicious Files in Dev Machine Guard](/developer-machines/malicious-files.md).
{% endhint %}


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stepsecurity.io/github/malicious-files.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.