Skip to content

Quickstart

Five minutes from zero to your first scan finding.

What you'll do

  1. Install Efterlev.
  2. Initialize a workspace in a sample Terraform repo.
  3. Run efterlev scan and see findings.
  4. (Optional) Run the Gap Agent for an LLM-classified report.
  5. (Optional) Use efterlev report run to chain everything into one command, with --watch for re-runs on file changes.

What you won't need: an account, a credit card, a SaaS dashboard, or a procurement approval. Efterlev runs locally on your machine.

Prerequisites

  • Python 3.12 or later. Check with python3 --version.

  • A Terraform repository to scan against. If you don't have one handy, clone the demo repo we use throughout this guide:

    git clone https://github.com/efterlev/govnotes-demo.git
cd govnotes-demo

1. Install

pipx keeps Efterlev isolated from your system Python while giving you a globally-callable efterlev CLI.

pipx install efterlev
efterlev --version

uv tool install efterlev
efterlev --version

No install needed; the container ships with everything baked in.

docker pull ghcr.io/efterlev/efterlev:latest
docker run --rm ghcr.io/efterlev/efterlev:latest --version

For container-based scans, prefix every command in this guide with:

docker run --rm -v $(pwd):/repo -w /repo ghcr.io/efterlev/efterlev:latest

Full per-platform install instructions →

2. Initialize the workspace

efterlev init --baseline fedramp-20x-moderate

This creates a .efterlev/ directory with:

  • The vendored FedRAMP FRMR catalog.
  • The vendored NIST 800-53 Rev 5 catalog.
  • A SQLite-backed provenance store.
  • A config.toml recording the baseline + LLM backend choices.

Output:

Initialized .efterlev/
  baseline:              fedramp-20x-moderate
  FRMR:                  v0.9.43-beta (2026-04-08, 11 themes, 60 indicators)
  NIST SP 800-53 Rev 5:  324 controls (+872 enhancements)
  load receipt:          sha256:4dad52a9...

3. Scan

efterlev scan

This runs 43 deterministic detectors against your Terraform (and .github/workflows/ for CI/supply-chain KSIs). No LLM calls, no network — pure local rules over your source files.

Expected output for the govnotes demo:

Scanning .
  ✓ aws.encryption_s3_at_rest        — 4 evidence records
  ✓ aws.tls_on_lb_listeners          — 1 evidence record
  ✓ aws.security_group_open_ingress  — 2 findings
  ...
66 detectors run, 73 evidence records, 14 findings.
HTML report: .efterlev/reports/scan-20260425T140530Z.html

Open the HTML report in your browser:

open .efterlev/reports/scan-*.html  # macOS
xdg-open .efterlev/reports/scan-*.html  # Linux

You'll see every finding with the .tf file and line number that produced it. Click any finding to walk back through the provenance chain.

4. (Optional) Run the Gap Agent

The Gap Agent uses Claude to classify each KSI as implemented / partial / not_implemented / not_applicable / evidence_layer_inapplicable, grounded in the scanner's evidence. The fifth status (SPEC-57.1) is for KSIs the scanner cannot evidence from infrastructure-as-code by design — procedural commitments like the FedRAMP Security Inbox — distinct from KSIs the CSP doesn't implement. This is the LLM step — it requires an API key.

export ANTHROPIC_API_KEY="sk-ant-..."
efterlev agent gap

First reconfigure your workspace to use Bedrock:

efterlev init --force \
  --baseline fedramp-20x-moderate \
  --llm-backend bedrock \
  --llm-region us-east-1 \
  --llm-model us.anthropic.claude-opus-4-7-v1:0

Then ensure AWS credentials are available (aws configure list or via instance profile). The Bedrock backend uses your existing AWS auth.

efterlev agent gap

For GovCloud, follow the GovCloud deploy tutorial →

The Gap Agent produces a second HTML report with each KSI classified and explained, every claim citing the underlying evidence by content-addressed ID.

Gap Agent: classified 60 KSIs in 47 seconds.
HTML report: .efterlev/reports/gap-20260425T140617Z.html
Cost: $1.24 (claude-opus-4-7 via anthropic-direct)

Every claim carries a DRAFT — requires human review marker. The agent never claims authorization.

5. (Optional) One command for the full pipeline

Once you're past the first-run mental overhead, efterlev report run chains every stage into one invocation:

efterlev report run

This runs init → scan → agent gap → agent document → poam in sequence, with stage headers so you can see progress. Add --watch to keep running and re-execute the pipeline on file changes (debounced 2 seconds):

efterlev report run --watch

Edit a .tf file and save — the pipeline re-runs automatically. Ctrl-C exits.

For comparing two scans (CI gating, drift detection):

efterlev report diff prior-gap-{ts}.json current-gap-{ts}.json

Exits with code 2 if any KSI regressed since prior — useful for blocking PRs in CI on posture regressions.

6. (Optional) Troubleshoot configuration

If something feels off — agent hangs, weird errors, missing files — run:

efterlev doctor

It checks Python version, .efterlev/ initialization state, FRMR cache freshness, ANTHROPIC_API_KEY shape, and AWS Bedrock credentials. Each check has a one-line remediation hint.

What's next

Troubleshooting

efterlev: command not found after pipx install — make sure ~/.local/bin is on your PATH. pipx ensurepath adds it.

error: ANTHROPIC_API_KEY is missing or invalid — set ANTHROPIC_API_KEY to a real key from https://console.anthropic.com (or switch to the Bedrock backend in .efterlev/config.toml). Run efterlev doctor to verify.

Init fails with baseline ... is not supported — current Efterlev supports fedramp-20x-moderate only. Other baselines land as customer demand surfaces.

Scan finds zero evidence — your detectors may not match your stack (we ship 66 detectors covering AWS Terraform + GitHub Actions workflows; non-AWS stacks see less coverage today). Check the detector reference for what's covered.

Anything else: open an issue — broken first-runs are bugs we want to hear about.