Security Compliance Mapping

Production engineering guide for security compliance mapping covering patterns, implementation strategies, and operational best practices.

Security Compliance Mapping is the disciplined process of linking abstract regulatory or contractual requirements—such as those found in SOC 2, PCI DSS, GDPR, or ISO 27001—to concrete technical controls, configuration states, code patterns, and operational checks within a system. It matters when you are preparing for an audit, designing or refactoring a system under regulatory constraint, onboarding to a new compliance framework, or integrating security requirements into CI/CD pipelines. The exercise is not a one‑time documentation task; it is an ongoing alignment between what is required and what the system actually enforces, updated as requirements evolve and as the system changes.

1. Catalogue Requirements into Structured Controls

The first step is to take a framework document—PDF, spreadsheet, or catalog—and extract individual controls into a machine‑processable form. Frameworks rarely provide data in a ready‑to‑query format, so normalisation is the primary practical work.

Concrete pattern: Convert the source to plain text if needed, then pull IDs and titles with standard text tools.

# Example: extract control IDs that start with CTRL- from a framework text dump
cat framework.txt | grep -E '^CTRL-[0-9]' > required-controls.txt

If the catalog is already in OSCAL JSON, the same result comes from jq:

jq -r '.controls[] | "\(.controlId) \(.title)"' oscal-catalog.json > required-controls.txt

The output file is a two‑column list: controlId title, one control per line. This flat list becomes the basis for all downstream comparison steps.

Sharp edge: Framework documents nest controls under families, sub‑controls, or hierarchical levels. A simple grep flattens the tree but loses parent‑child relationships. If a control “CTRL‑0151” sits under “Family A” and another “CTRL‑0152” under “Family B”, a flat list treats them as peers. You’ll need to decide whether to preserve the path (e.g., A::CTRL‑0151) for later filtering, or to denormalise consciously and accept that semantic grouping must be re‑added by human review later. Many organisations maintain a small spreadsheet or SQLite table that maps each flat ID to its original hierarchy, and treat that table as the canonical reference for the mapping exercise.

2. Extract the Current Technical State

Once the required controls are catalogued, the next task is to discover what the system actually implements. The inventory method depends on the layer: network, IAM, encryption, logging, code, or third‑party integrations.

Concrete pattern: query a central control registry.

psql -U secadmin -d infra -c \
  "SELECT control_id, setting_value, updated_at \
   FROM control_state \
   WHERE environment='prod';" > implemented-controls.txt

This assumes the organisation maintains a PostgreSQL (or equivalent) table that tracks which controls are active, their current value, and the last update timestamp. If no such registry exists, you can inventory through the platforms that are already instrumented.

Concrete pattern: list Kubernetes‑enforced policies.

kubectl get networkpolicies -A -o json \
  | jq -r '.items[].metadata.name' > impl-netpols.txt

Concrete pattern: search Git history for relevant changes.

git log --all --oneline --grep='[Ff]irewall\|[Ii]am\|[Ee]ncrypt' > relevant-commits.txt

Sharp edge: Configuration drift is the most common silent failure. A control may have been implemented once—e.g., a network policy that permits only TLS‑terminated traffic—but later overridden by a Helm values override, an environment‑variable flag, or a runtime admission controller that bypasses the original intent. kubectl diff against the desired‑state chart can reveal drift, but only if the chart is the source of truth. Without that anchor, you’re mapping to an outdated snapshot, and the gap you report is a false positive.

3. Compare Required vs Implemented and Surface Gaps

With two lists—required controls and implemented controls—the mapping reduces to a set difference. The goal is three buckets: fully mapped, partially mapped, and unmapped.

Concrete pattern: sorted‑file comparison with comm.

sort required-controls.txt > req_sorted.txt
sort implemented-controls.txt > impl_sorted.txt

# Controls required but not yet implemented
comm -23 req_sorted.txt impl_sorted.txt > unmapped-gaps.txt

# Controls with a matching entry
comm -12 req_sorted.txt impl_sorted.txt > fully-mapped.txt

Concrete pattern: keyword‑based fuzzy check for partial matches.

grep -i "firewall" required-controls.txt | while read -r line; do
  if grep -iq "$line" implemented-controls.txt; then
    echo "MATCH: $line"
  else
    echo "GAP: $line"
  fi
done

Concrete pattern: jq‑driven diff for JSON‑based maps.

jq -r '.required[].id' map.json | comm -23 - \
  <(jq -r '.implemented[].id' map.json) > gaps.txt

Sharp edge: Terminology mismatch causes the majority of false negatives. A framework may describe a control as “data‑at‑rest encryption”, while the implementation labels it “AES‑256 at rest”, “disk‑encryption‑enabled”, or “TDE‑active”. Exact string matching misses all three. Normalising to lowercase, stripping common prefixes (enc, tde, aes), and using stemmed keywords (via awk '{print tolower($0)}') reduces the problem but does not eliminate it. You’ll still need human review for semantic mapping, especially when control descriptions use domain‑specific language that a simple grep cannot capture.

4. Automate the Mapping in a CI/CD Pipeline

To keep the map current, embed the comparison step in a pipeline that runs on every config change, deployment, or scheduled audit window.

Concrete pattern: GitHub Actions job that inventories and diffs.

jobs:
  compliance-map:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Inventory implemented controls
        run: |
          psql -h db -U ${{ secrets.DB_USER }} -d infra \
            -c "SELECT control_id FROM control_state WHERE env='staging';" \
            > implemented-controls.txt

      - name: Map against requirements
        run: |
          sort required-controls.txt > req_sorted.txt
          sort implemented-controls.txt > impl_sorted.txt
          comm -23 req_sorted.txt impl_sorted.txt > gaps.txt
          if [ -s gaps.txt ]; then
            echo "::error::Unmapped controls found:"
            cat gaps.txt
            exit 1
          fi

Sharp edge: Secrets management in CI. The job above references secrets.DB_USER and a PostgreSQL host. If those secrets are missing or have rotated, the step fails with an opaque connection error, not a compliance gap. The pipeline becomes untrustworthy if every failure reads “database unreachable” instead of “gaps detected”. A robust pattern adds a fallback that produces a “could not inventory” marker file and lets the diff step either skip or flag the condition explicitly, rather than hard‑failing the entire job.

Another subtlety: the pipeline runs against a staging environment. Staging may not reflect production state—feature flags, canary releases, or environment‑specific overrides can make the inventory stale. Document the environment scope explicitly in the job name and in the generated report (“last validated against staging‑as-of 2025‑08‑22”).

5. Produce a Report for Stakeholders

The final output of a mapping exercise is typically a human‑readable gap report, often in PDF or HTML, plus a machine‑readable artifact (CSV, JSON, OSCAL) that auditors can ingest.

Concrete pattern: shape diff results with jq and write CSV.

jq -r '.gaps[].id' gaps.txt > gap-ids.txt
jq -r '{gaps: [inputs from unmapped], mapped: [inputs from mapped]}' \
  diff-results.json > compliance-report.json
csvformat -K control_id,title,status gap-ids.txt > non-compliant-controls.csv

Concrete pattern: fill a Markdown template with envsubst.

envsubst < template.md.in > compliance-report.md

where template.md.in contains placeholders like ${GAP_COUNT} and ${FULLY_MAPPED_COUNT} that are exported from the preceding comm steps.

Sharp edge: Report staleness. If the mapping script runs weekly but controls change daily, the report reflects the state at pipeline run time, not current reality. Auditors flag this as “evidence not current”. Add a “last validated” timestamp to every report, and version the mapping script itself alongside the requirements catalog. If your organisation uses Git, commit the script and the generated report together in a mapping/ directory; the git history then becomes the audit trail of how the map evolved.

6. Maintain Mapping Integrity Over Time

Compliance mapping has no project end date. Frameworks update (new versions, new controls), systems evolve (micro‑service refactors, cloud migrations), and organisational scope changes.

Practice: Store requirements in version control. Tag each catalog version. Tag each mapping run. Use a changelog for control additions, removals, or textual changes. Re‑run the mapping script on catalog version bumps and commit the new diff as a versioned mapping artifact.

Concrete pattern: When a new OSCAL catalog version is released, download the remote description and re‑run the mapping.

oscap info --fetch-remote-description https://example.com/catalogs/v2.1.oscal \
  > remote-metadata.xml
# then re‑run the jq/ comm pipeline against the new IDs

(If your organisation does not use OSCAL, replace the oscap step with whatever mechanism delivers the new control list—e.g., a curl fetch of a JSON endpoint, a Git tag push, or a spreadsheet import.)

Sharp edge: Control inheritance. A parent control may subsume multiple child controls. Mapping them as independent items creates double‑counting (a child counted separately from its parent) or gaps (a parent‑only requirement overlooked because its children were mapped). Track control relationships in a small data model—e.g., a SQLite table with control_id, parent_id, relationship_type—and query accordingly before generating the gap list. A simple query like:

sqlite3 mapping.db "SELECT c.control_id, p.control_id AS parent
FROM controls AS c
LEFT JOIN controls AS p ON c.parent_id = p.control_id;"

reveals which controls are children of others, allowing you to flatten or aggregate as needed.

Closing principle

Keep the mapping data close to the source of truth. If requirements live in a spreadsheet that is updated ad‑hoc, that spreadsheet becomes the single point of failure—any drift between the sheet and the actual system goes undetected. Prefer machine‑processable formats (OSCAL JSON, YAML in Git, PostgreSQL tables) and treat the mapping script as the canonical transformer. Update the script when the format changes, not the other way around. Version‑control everything: the requirements catalog, the inventory scripts, the diff results, and the generated reports. The git history then becomes the audit trail of how your compliance alignment evolves.

This page was rewritten on 17 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.