CipherMap Documentation

How it works: Runs a fast, strictly read-only readiness assessment across local language manifests (go.mod, package.json, pyproject.toml/requirements.txt, Cargo.toml, .csproj, pom.xml/build.gradle) and local compilers without mutating files. Categorizes findings into four actionable buckets: ready_for_auto_upgrade, co_hardening_recommended, architectural_or_mcp_assisted, and environment_setup_needed.
Access: Free & Tier A evaluate PQC cryptographic readiness and local toolchain prerequisites; Tier B Enterprise Fleet adds unified PQC + 12-Language Immunity Pre-Migration Safety Shield analysis to flag PQC call sites co-located in the same handler/scope as unguarded IMM-* sinks.

ciphermap preflight . --offline --no-telemetry
ciphermap preflight ./services/api --exclude-vendored -f json -o preflight.json

How it works: Full-screen Charmbracelet bubbletea/lipgloss TUI over your scan results: a findings list, per-rule explainer drawer with 12-language NIST FIPS 203 (ML-KEM-768) and FIPS 204 (ML-DSA-65) migration blueprints, planning views, candidate diffs, and a remediation studio (ciphermap fix . --studio).
Access: Read-only inspection and proposal preview are Free. Ctrl+E encrypted vault export requires Tier A+. Source actions require a compatible entitlement, eligibility, and the relevant project-verification setup.

ciphermap tui . --offline --no-telemetry              # interactive findings & FIPS 203/204 blueprint viewer
ciphermap fix . --studio --offline --no-telemetry     # interactive Gate 2 remediation studio (Tier B)

Start with a preview: Dry-run lists candidate plans and decline reasons without modifying files. Use --patch to inspect candidate diffs and --blueprint for migration guidance. By default, --immunity-precheck (true) runs the Pre-Migration Safety Shield on PQC target files and warns when PQC call sites share an enclosing handler/scope with unguarded IMM-* bug classes. Eligibility varies by language, call shape, module format, and persistence or protocol context.
Before applying: Gate 2 classical PQC --apply requires Tier A (Standalone Auditor) or Tier B, a trusted repository, discoverable project verification, and explicit --allow-verify-exec consent. Passing --with-immunity with --apply requires Tier B Enterprise Fleet (immunity.extinguish + remediation.write) on a clean Git worktree, committing 4-Gate verified Immunity fixes first and running the Gate 2 PQC transaction on top. A syntax check is different from compiling or passing application tests; review the selected verifier and its output.

ciphermap fix . --dry-run --offline --no-telemetry
ciphermap fix . --patch --offline --no-telemetry
ciphermap fix . --blueprint --offline --no-telemetry
# Tier A+: Gate 2 classical crypto remediation after reviewing eligibility & project verification:
ciphermap fix . --zero-attestation --apply --allow-verify-exec --offline --no-telemetry
# Tier B Enterprise: single-pass 4-Gate Immunity pre-hardening + Gate 2 PQC migration:
ciphermap fix . --with-immunity --apply --allow-verify-exec --offline --no-telemetry

Export detected cryptographic assets as CycloneDX 1.6 with cryptoProperties, or select SPDX/OpenVEX. Unknown fields are omitted and coverage limits still apply.
Bundle integrity: --bundle --output audit.zip packages the documents with an HMAC-SHA256 manifest. Configure an organization-controlled CIPHERMAP_SIGNING_KEYand use the same secret for verification. HMAC is not a public-key digital signature.
Optional PQC bundle provenance: Supply both --pqc-cert and --pqc-device-key using separately provisioned credentials. A license alone does not configure signing or verifier trust. Local generation, posture comparison, and bundles require Tier A; configured Dependency-Track delivery requires Tier B.

ciphermap cbom . --format cyclonedx --output cbom.json --offline --no-telemetry
# Bundle creation and verification use the same configured CIPHERMAP_SIGNING_KEY:
ciphermap cbom . --bundle --output audit.zip --offline --no-telemetry
ciphermap cbom --verify audit.zip --offline --no-telemetry
ciphermap cbom --diff baseline-cbom.json,release-cbom.json --output cbom-diff.json --offline --no-telemetry

How it works: Decrypts an AES-256-GCM encrypted .enc vault archive and extracts its compliance documents.
Why it matters: Lets an analyst on an isolated network read audit results produced on the other side of the air gap.
Access: Standalone Auditor Tier A or DevSecOps Enterprise Tier B.

# Requires the vault passphrase supplied via CIPHERMAP_VAULT_PASSPHRASE.
ciphermap import vault.enc --output ./audit --offline --no-telemetry

How it works: Verifies the SHA-256 checksum manifest (vault.enc.sha256) against the encrypted vault package before extraction. Verification is free, so an auditor who is not a customer can still check a bundle's integrity.
Why it matters: Detects corruption or truncation after physical media transfer, before you attempt decryption.

ciphermap verify vault.enc --offline --no-telemetry

GitHub / GitLab / Bitbucket PR Review & Automated Jira Reconciliation

ciphermap ci-review runs the Tier B PR review bot for GitHub, GitLab, Azure DevOps, Bitbucket Cloud, or Bitbucket Server using idempotent [ciphermap-fingerprint:...] markers so repeated pipeline runs reconcile matching comments. Select the review domain with --domain crypto | immunity | all (default crypto) and attach composite-signed Vericoding evidence via --proof <proof-bundle.json> (auto-detected from .ciphermap-immunity-proof.json in persisted HEAD when present). Pair it on post-merge with ciphermap jira . --resolve-remediated --apply, which deduplicates open issues via ciphermap-fp-* labels and automatically transitions remediated findings to Done / Resolved. The plain CI gate via scan --fail-on is Free. Exit-code contract: 0 clean, 1 gate tripped, 2 error — a read failure exits 2 rather than passing silently. Basic provider templates, the composite GitHub Action, and the pre-commit hook also remain Free; writing PR comments or checks is the Tier B boundary.

This connected example assumes an approved Linux x64 binary is provisioned at /opt/ciphermap/ciphermap on an isolated, trusted runner, a compatible Tier B credential, and provider permissions. Set the protected repository variable CIPHERMAP_BINARY_SHA256 to that binary’s independently verified digest. The general installer remains a separate release gate. Use this only for approved internal pull requests, not untrusted forks. It checks out the exact PR head with full history; configure a protected policy and base before enabling blocking mode.

name: CipherMap PR Review
on: [pull_request]
jobs:
  review:
    runs-on: [self-hosted, linux, x64, ciphermap-approved]
    permissions:
      contents: read
      pull-requests: write
      checks: write
    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0
          persist-credentials: false
      - name: Verify the provisioned binary
        env:
          CIPHERMAP_BINARY_SHA256: ${{ vars.CIPHERMAP_BINARY_SHA256 }}
        run: |
          [[ "$CIPHERMAP_BINARY_SHA256" =~ ^[a-fA-F0-9]{64}$ ]]
          printf '%s  /opt/ciphermap/ciphermap\n' "$CIPHERMAP_BINARY_SHA256" | sha256sum --check --status
      - run: /opt/ciphermap/ciphermap ci-review . --provider github --pr ${{ github.event.number }} --domain all --mode blocking --fail-on critical
        env:
          GITHUB_TOKEN: ${{ github.token }}
          CIPHERMAP_LICENSE: ${{ secrets.CIPHERMAP_LICENSE }}

Inspect, list, and optionally share strictly bounded 6-field, 12-token closed-vocabulary AST skeleton receipts (.ciphermap/herd-patterns/HERD-*.json) when a polyglot edge-case declines automatic remediation. Every identifier name, string literal, numeric literal, comment, file path, and repository identity is stripped locally before disk persistence. Persistent flags: --workspace <dir> and -f, --format text | json.

# 1. Preview exact 6-field zero-code receipt locally (zero network egress):
ciphermap herd-immunity preview ./src/db.rs --line 42 --rule IMM-SQLI-001 --compiler-code E0308 --no-save

# 2. List queued local pattern receipts in .ciphermap/herd-patterns/:
ciphermap herd-immunity list --format json

# 3. Explicitly opt in to share a verified receipt:
ciphermap herd-immunity share .ciphermap/herd-patterns/HERD-A1B2C3D4E5F6.json

Prometheus Metrics

The self-hosted fleet server (ciphermap server) exports Prometheus-format metrics at /metrics — ciphermap_fleet_complete_scan_score, ciphermap_scans_processed_total, and ciphermap_repos_monitored_total. Fleet operation requires DevSecOps Enterprise Tier B. Only /healthz is public. Metrics, the console, reports, policy and management APIs require the admin token. Keep the server-only ingest signing key out of CI; mint a separate write token for each canonical repository. A repository token cannot write another repository or read fleet data. Repository badges use a separately revocable badge token.

# Operator: mint one repository-scoped CI credential
CIPHERMAP_SERVER_INGEST_KEY="$SERVER_KEY" \
  ciphermap server --mint-ingest-token acme/payments

# CI: publish only this repository's scan evidence
CIPHERMAP_SERVER_INGEST_TOKEN="$ACME_PAYMENTS_TOKEN" ciphermap sync . --server-url "$CIPHERMAP_SERVER_URL"

# Admin/Prometheus: read fleet metrics
curl -s -H "Authorization: Bearer $CIPHERMAP_SERVER_TOKEN" \
  http://localhost:8080/metrics | grep ciphermap_fleet_complete_scan_score