vigilante-scan 0.3.2

See what a pull request lets your code, your CI, and your AI agents do, before you merge it.

Vigilante reads a pull request and lists the new powers that the pull request adds. A power is an action that a change lets code, CI, a build, or an AI agent do. Examples are the first subprocess call in a package, a CI token that can push, a new MCP server, and a new install script.

Your security team approves powers in a vigilante.lock file. If a pull request adds a power that is not in the lock, the check fails.

By default, Vigilante does not run code from the repository that it checks. It reads the files and resolves calls by type. It uses Capslock for Go, the TypeScript type checker for JavaScript and TypeScript, and Pyright for Python. These tools read code, and they do not run it. Vigilante also downloads the locked packages from their public registries and reads them. If you set [engines] rust = "typed", Vigilante builds the Rust code in a Docker container that has no network access (docs/dependencies.md).

Why

AI agents open more pull requests than people can read line by line. A one-line change can change what each later agent run and CI job can do. Examples are a change to .mcp.json, .claude/settings.json, a workflow, or a postinstall script. Vigilante shows these changes at the top of the pull request. It uses the same format for each language and each type of file.

Example

An agent opens a pull request that exports invoices. Vigilante gives this report:

Vigilante: this pull request adds 6 new powers

Result: fail. 6 powers are not in vigilante.lock. Run vigilante lock and commit the file.

Severity	Scope	Power	What it means	Evidence	Status
HIGH	services/billing (code)	exec	Can run other programs	services/billing/billing/export.py:5 via export.export → subprocess.run	not in lock
HIGH	.mcp.json (agent)	mcp_server:fs-tools: npx -y fs-tools-mcp	The agent connects to an MCP server	.mcp.json:3	not in lock
MEDIUM	.github/workflows (ci)	third_party_action:acme-tools/publish-action	The workflow runs a third-party action	.github/workflows/release.yml:12	not in lock
MEDIUM	.github/workflows/release.yml (ci)	token_write:contents	The CI token can write to the repository	.github/workflows/release.yml:6	not in lock
MEDIUM	.github/workflows/release.yml (ci)	secret:PYPI_TOKEN	The workflow reads a secret	.github/workflows/release.yml:14	not in lock
MEDIUM	.claude/settings.json (agent)	tool_allow:Bash(curl:*)	The agent can use a tool without asking	.claude/settings.json:3	not in lock

The same pull request also added a second network call to services/billing, the allow rules Bash(pytest:*) and Read, and a call to actions/checkout. Vigilante does not report them, for these reasons:

• The package already used the network.
• An allow rule for a test runner has a low risk.
• Read only reads files.
• The actions/ actions are first party.

What it checks

Vigilante reports a power the first time that it appears in a scope. After that, it reports each changed risk. Some risks block until vigilante.lock approves them. Examples are a call with untrusted input, and a workflow script that reads the title of a pull request. See docs/risks.md. For code, a scope is the nearest package root. For Go, a scope is the Go package. Vigilante skips vendored code. It reports tests and fixtures as test code, apart from the findings. See docs/powers.md for each power and for the rules that keep the report short.

A finding is exec, network, or native that your package reaches through its own code. This rule is the same in each language. All other results are notes:

• another power that your own code reaches;
• a power that your package reaches only through a dependency, or through another package of the same repository;
• a new package on a call path to a power.

Notes do not make the check fail, unless a deny rule matches their power. For example, a new dependency that reaches the network is a note. docs/dependencies.md tells you how Vigilante reads packages.

Install

Vigilante is one static binary for Linux and macOS, on x86_64 and arm64. Use the package manager that your team uses. The command is always vigilante.

Each release file has a build attestation. To make sure that an archive comes from the release workflow of this repository, run this command:

gh attestation verify vigilante-x86_64-unknown-linux-musl.tar.gz --repo theonly1me/vigilante

Vigilante does not support Windows. To check Go code, Vigilante needs go and capslock. To install Capslock, run go install github.com/google/capslock/cmd/capslock@v0.3.3. The GitHub Action installs both.

Quick start

Run these commands in the root of your repository.

diff and check write Markdown. For other tools, add --format json or --format sarif.

Run it on each pull request

Add .github/workflows/vigilante.yml:

name: Vigilante
on:
  pull_request:
  push:
    branches: [main]
permissions:
  contents: read
jobs:
  vigilante:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
          persist-credentials: false
      - uses: theonly1me/vigilante@v0.3.2

On a pull request, the action runs vigilante diff against the base branch. On a push, it runs vigilante check. The action writes the report to the job summary. The job needs no secrets, so it also works on pull requests from forks. To also write the report as a comment on the pull request, set comment: true and give the job the permission pull-requests: write.

Then make your security team the owner of the lock in CODEOWNERS. Also turn on "Require review from Code Owners".

vigilante.lock      @your-org/security
vigilante.toml      @your-org/security
.github/            @your-org/security

After this change, each pull request that adds a power must change vigilante.lock. The security team must approve that change. Run vigilante doctor to make sure that GitHub enforces these rules. docs/github-action.md gives the full setup. It also tells you how to protect the check and how to use Vigilante in other CI systems.

Use it with AI agents

Tell your agents to run vigilante diff --base origin/main before they open a pull request. If an agent adds a power on purpose, tell it to run vigilante lock. The pull request then shows the new powers, and the change to the lock asks for the correct review.

Configuration

Vigilante works with no configuration. To change what it reports, add vigilante.toml:

[scan]
exclude = ["examples/**"]

[policy]
deny = [{ scope = "services/**", capability = "exec" }]

[ci]
trusted_owners = ["your-org"]

In a pull request, Vigilante reads vigilante.toml from the merge base. So a pull request cannot change the rules that check it. docs/configuration.md lists each key and the lock format. It also tells you how to add rules for your own wrappers.

What Vigilante is not

• It is not a malware detector. It shows what changed, and a person decides if the change is safe.
• It does not follow calls that the code makes at run time, such as reflection, eval, or metaprogramming.
• It uses no AI to find or sort powers. The same input gives the same output.
• It downloads packages only from public registries and from the registries that you allow. It keeps them in a cache.

Contribute

Read CONTRIBUTING.md. To report a security problem, read SECURITY.md. docs/README.md lists all the documentation.

License

You can use Vigilante under the Apache License 2.0 or the MIT license.