# Chargate

> Markdown source of https://docs.magmamoose.com/chargate/.

<!-- sources: action.yml, src/chargate/cli.py -->

Chargate is a **security + lint gate** built on [MegaLinter](https://megalinter.io).
MegaLinter does **all** the scanning; Chargate adds the one thing that matters for
day-to-day developer flow: **net-new finding gating**.

On a pull request the gate passes or fails based *only* on findings the PR
introduces relative to the merge-base. **Pre-existing findings never block.** The
full, unfiltered SARIF is always emitted and shippable (first-class DefectDojo
import, GitHub Security tab, or build artifact), and a CycloneDX BOM can be shipped
to Dependency-Track, so your security system still sees everything, including
inherited debt.

!!! note "v2 is a ground-up re-platform"
    Chargate no longer hand-rolls a 12-tool scanner orchestration, MegaLinter
    does that. If you used `magmamoose/chargate@v1`, see
    [Migrating from v1](https://docs.magmamoose.com/chargate/setup/#migrating-from-v1).

## Why net-new?

A whole-repo security scan on a large codebase reports hundreds of pre-existing
findings. Blocking PRs on all of them is noise; ignoring them loses signal.
Chargate splits the difference:

- **Gate** on what *this PR* introduced (net-new) → actionable, low-noise.
- **Ship** the *complete* SARIF to DefectDojo / the Security tab (and a CycloneDX
  BOM to Dependency-Track) → full visibility, including inherited debt and trends.

## Two surfaces, one CLI

| Surface | What it is | When to use |
| --- | --- | --- |
| **Composite action** | `action.yml` | The CI gate, a few lines in a workflow. |
| **pre-commit hook** | `.pre-commit-hooks.yaml` (`chargate` hook) | Fast local first line on staged files. |

Both drive the same `chargate` Python CLI. See [Setup & usage](https://docs.magmamoose.com/chargate/setup/) to
wire one up, [Architecture](https://docs.magmamoose.com/chargate/architecture/) for how it fits together, and
[Net-new gating](https://docs.magmamoose.com/chargate/net-new/) for the precise classification rules. Every input and
output of the action is listed in the [Action reference](https://docs.magmamoose.com/chargate/action-reference/).

Another tool can gate on Chargate's classification without importing any of it: every
run writes a net-new SARIF and a versioned counts JSON, documented as a stable
interface in [Consuming the output](https://docs.magmamoose.com/chargate/consuming-output/).

## PR comments

On a pull request Chargate posts its net-new findings as GHAS-style comments. Give the
job `id-token: write` and those comments are authored by `Chargate[bot]` instead of
`github-actions[bot]`, via a token broker that runs as an AWS Lambda. The exchange is
fail-soft: if anything goes wrong you still get the comments, just under the
`github-actions[bot]` name and with a warning in the log. See
[Troubleshooting](https://docs.magmamoose.com/chargate/troubleshooting/) if the byline is not what you expect.

## Modes

- **PR events** → whole-repo MegaLinter → net-new gate → full SARIF to the
  sinks / artifact.
- **Push to default branch / scheduled** → full scan → full SARIF to the sinks as
  the authoritative baseline → **no** net-new gate.

`mode: auto` (default) picks this from the event; force it with `mode: pr|baseline`.

## Lineage

Chargate is the public productization of the security side of
`CalebSargeant/pre-commit-hooks` → `CalebSargeant/cinnabar`. The formatting /
file-hygiene / Actions-SHA-pinning hooks stay in `pre-commit-hooks`; the
`chargate` hook is the security + lint first line and is meant to coexist.

## License

Apache 2.0.