Skip to main content
Glama
README.md
# Security in the Loop

Offline security feedback for AI coding agents through MCP.

## Project idea

Static scanners check the code the agent proposes. Their findings point to
specific rules and source locations so the agent can revise the edit before
the helper applies the approved bytes.

![A proposed edit is scanned, revised from findings when needed, and applied through a checked write when policy allows it.](docs/images/feedback-loop.svg)

## Quick start

The verified `0.5.0` release candidate uses a macOS ARM64 helper and a Linux ARM64
Docker image. [Verified release scope](docs/RELEASE.md).

Clone this repository and start at its root on an Apple silicon Mac with
Docker Desktop. You will prepare the Trivy database and build artifacts locally.

1. Prepare the pinned scanners and fresh Trivy data, then build the image and
   helper. [Build from source](docs/BUILDING.md).
2. Set up a project in Codex and review its project hooks. Setup configures the
   private MCP URL and runs the scanner services in Docker. [Connect Codex](docs/GETTING_STARTED.md).
3. Ask Codex to create a small file through the checked write path. Check for
   an applied receipt and acknowledgment. [Try one checked edit](docs/GETTING_STARTED.md#5-try-one-coding-request).

If you have a helper archive and its matching local image, use the
[local bundle guide](docs/INSTALL_LOCAL.md).

## How it works

![The project hook and helper send isolated snapshots to Docker over loopback MCP. The offline worker scans them, and the helper applies approved edits on the host.](docs/images/host-and-docker.svg)

A project hook holds a supported edit while the helper captures the worktree.
The helper sends isolated baseline and candidate snapshots to the loopback MCP
gateway. A worker with networking disabled scans those snapshots. Codex receives
findings and can revise the proposal. The helper verifies the current worktree
and records a receipt when it applies the approved bytes.

Project folders stay on the host. Downloads happen during explicit preparation
or data maintenance. Scans use pinned engines and prepared local data.

The hook boundary is `checked_path_only`. An exclusive write boundary requires
a harness that controls every write path. [Architecture](docs/ARCHITECTURE.md).

## Scanner coverage

| Area | Scanners |
| --- | --- |
| Source code | Semgrep CE, Bandit, Gosec |
| Secrets | Gitleaks, TruffleHog |
| Dockerfiles | Hadolint |
| Infrastructure configuration | Trivy, Checkov, KICS |
| Supported dependency inventories and image archives | Trivy |

Scanner API keys and database servers are unnecessary. Unsupported inputs,
scanner failures, and missing, stale or corrupt required data are explicit
errors. [Supported inputs and policy](docs/COVERAGE.md).

## Development and verification

- [Client compatibility and evidence](docs/CLIENT_COMPATIBILITY.md)
- [Repository layout](docs/PROJECT_STRUCTURE.md)
- [Release scope and verification](docs/RELEASE.md)
- [Implementation plan](PHASED_IMPLEMENTATION_PLAN.md)
- [Contributing](CONTRIBUTING.md) and [reporting a vulnerability](SECURITY.md)

## License

Copyright 2026 sathwikv143. The project's original source is licensed under
Apache 2.0. The scanner tools have their own license terms.
[Project license](LICENSE) · [Upstream scanner notices](docker/licenses/)