COMPLYCTL-PROVIDER-AMPEL(1)

💖 NAME 💖

okay bestie, welcome to complyctl-provider-ampel(1) — it's the Ampel scanning provider for complyctl, and it lives in the General Commands Manual section like the absolute icon it is ✨

---

🌸 SYNOPSIS 🌸

complyctl-provider-ampel

🦋 DESCRIPTION 🦋

so complyctl-provider-ampel is a gRPC plugin for complyctl(1) that hands out compliance scanning powers using the Ampel evaluation engine. and like — no cap — you don't run this yourself. it's not that kind of program. complyctl finds it and launches it all on its own the moment the provider is installed. main character energy, but make it a subprocess 💅

what it actually does: it takes assessment configurations from complyctl and evaluates repository configurations against granular security policies (think branch protection rules, that kind of thing) using the snappy and ampel CLI tools. results come back with per-tenet messages and remediation guidance, which is genuinely so helpful of it 🫶

the talking-to-complyctl part happens over the hashicorp/go-plugin gRPC interface, and it implements exactly three RPCs: Describe, Generate, and Scan. three. that's the whole squad. periodt.

---

🎀 CONFIGURATION 🎀

the config comes through variables defined in assessment plan targets. these get passed to the provider via complyctl — you do not set them by hand, bestie. hands off 🙈

• url (required) — the HTTPS URL of the repository to scan. it must use the HTTPS scheme, no exceptions. example: https://github.com/org/repo
• specs (required) — a comma-separated list of spec references identifying which policy files to evaluate. example: builtin:github/branch-rules.yaml. and heads up — path traversal sequences (../) get rejected. nope nope nope 💀
• branches (optional) — comma-separated list of branches to scan. has to match the pattern [a-zA-Z0-9._/-]+. path traversal sequences are rejected here too. default: main
• access_token (optional) — authentication token for getting into private repositories. rejected if it contains newlines or null bytes. keep it clean ✨
• platform (optional) — a platform hint for self-hosted instances (e.g., github, gitlab). used when hostname-based detection fails to figure out the platform. default: auto-detected from the URL hostname.
• ampel_policy_dir (optional, global variable) — a custom directory holding granular Ampel policy source files. takes second priority after complypack content. default: .complytime/ampel/granular-policies/

---

🌈 ENVIRONMENT 🌈

• COMPLYTIME_MACHINE_ID_FILE — path to the machine-id file used for host identification in evidence remarks. the file's content gets dropped into each Evidence.Source.Remarks field alongside the hostname, so auditors can tell which host the scan ran on. default: /etc/machine-id

---

🔥 EXTERNAL TOOLS 🔥

you need the snappy and ampel CLI tools present at runtime. ampel version 1.4.2 or later is required — that's the version that brought SKIP handling and the –allow-skip flag 🎉. the provider checks the ampel version at Generate/Scan time and, if what you've got is below the minimum, it reports an actionable error instead of just vibing into the void.

not me having to tell you this but: these tools are not currently packaged in Fedora and must be installed separately 😭

installation instructions live over in the Carabiner project: https://github.com/carabiner-dev

---

🍓 FILES 🍓

• .complytime/ampel/ — the provider workspace directory. every path below is relative to the current working directory, iykyk.
• .complytime/ampel/results/<repo>-<branch>-<spec>-snappy.intoto.json — the in-toto attestation produced by snappy snap. contains the raw API data collected from the repository (e.g., branch protection rules). the filename encodes the sanitized repository URL, the branch, and the spec label.
• .complytime/ampel/results/<repo>-<branch>-<spec>-ampel.intoto.json — the in-toto attestation produced by ampel verify. contains the policy evaluation results against the snappy-collected data. filename follows the exact same pattern as the snappy attestation.
• .complytime/ampel/results/<repo>-<branch>.json — per-repository result JSON, summarizing findings for a single repository + branch combo.
• .complytime/ampel/generated/<content-key>/scan-config.json — scan configuration written by the Generate RPC. it records the matched requirement IDs so the Scan RPC can synthesize passing assessments for requirements that had no findings. clever girl 💅
• .complytime/ampel/generated/<content-key>/ — the merged AMPEL policy bundle, generated from granular policy files.
• .complytime/ampel/generated/generate-index.json — maps each generated target to its content-keyed scan configuration and policy bundle. the little index that keeps track of everyone 🎀
• .complytime/ampel/granular-policies/ — default directory for granular AMPEL policy source files. overridden by ampel_policy_dir or complypack content.

---

👑 EVIDENCE 👑

the provider records Evidence entries on every AssessmentLog returned by the Scan RPC. per repository/branch/spec combination you get two attestation types:

⭐ Snappy attestation (type: IntotoAttestation)

the snappy tool collects raw API data from the repository platform (e.g., GitHub branch protection settings) and produces an in-toto attestation. this one captures the observed state of the repository at scan time. a literal snapshot, hence the name, obsessed 🌸

• Source.Coordinate: path to the snappy attestation file
• Source.Digest: sha256:<hex> digest of the attestation file
• Source.ReferenceID: snappy-<repo>-<branch>-<spec-label>

⭐ Ampel attestation (type: IntotoAttestation)

the ampel tool evaluates granular security policies against the snappy-collected data and produces an in-toto attestation holding the evaluation results.

⚠️ real talk: a non-zero exit code here means policy failures, not tool errors. don't panic-misread it 💀

• Source.Coordinate: path to the ampel result attestation file
• Source.Digest: sha256:<hex> digest of the attestation file
• Source.ReferenceID: ampel-<repo>-<branch>-<spec-label>

---

💜 EXIT CODES 💜

this provider is a gRPC subprocess managed by complyctl, so exit codes follow the hashicorp/go-plugin protocol and are not user-facing. nothing for you to read here, bestie, move along 🧚

---

🫶 SEE ALSO 🫶

complyctl(1), complyctl-provider-openscap(1), complyctl-provider-opa(1)

project: https://github.com/complytime/complytime-providers

---

✨ COPYRIGHT ✨

Apache-2.0 — slay, free and open, as always 💖

🌟 AUTHORS 🌟

Marcus Burghardt <maburgha@redhat.com> — thank you for your service 🫡

---

and that's the whole page, bestie!! this was the ComplyTime Manual, September 2026 edition, of COMPLYCTL-PROVIDER-AMPEL(1) — go forth and scan responsibly, ily, bye 💅✨🎀