Map Parse Framework

Service Approval — Map: Parse Framework

Parse a customer-provided control framework file into a normalized array of framework objectives. This is the smallest, most deterministic sub-skill in the map pipeline.

Scope note (as of 2026-05-16): the intake skill narrows interactive runs to CCMv4-only. Multi-framework parsing (NIST 800-53 / CIS / ISO 27001) remains available behind the --framework=<type> CLI flag for advanced operators who bypass intake. See skills/intake/SKILL.md for the rationale.

Input: Framework file (xlsx/json/md) or built-in CCMv4 reference Output: .service-approval/<slug>/04-map/map-framework-parsed.json

This is one of 4 focused map sub-skills. Each writes to a separate intermediate state file.

Prerequisites

mkdir -p .service-approval/<slug>/04-map

Inputs

Parse arguments:

• --framework=<type> — framework identifier (default: auto-detect from file)
• --framework-file=<path> — explicit path to framework file (overrides auto-detection)

Auto-detect framework file

If --framework-file is not provided, scan the input folder for framework files:

• .xlsx files containing "CCMv4", "ccmv4", "CSA", "cloud controls matrix" in filename -> CCMv4
• .xlsx files containing "NIST", "800-53" in filename -> NIST 800-53
• .xlsx files containing "CIS" in filename -> CIS Benchmarks
• .xlsx files containing "ISO", "27001" in filename -> ISO 27001
• .json files with top-level framework or controls key -> parse and detect
• .md files with framework headers -> parse and detect

If multiple framework files found, ask the user which to use. If no framework file found and --framework is set, use built-in domain reference.

Step 1: Parse Framework File

For .xlsx files (e.g., CCMv4_LightningLane.xlsx):

python3 -c "
import openpyxl, json, sys
wb = openpyxl.load_workbook(sys.argv[1], read_only=True, data_only=True)
for sheet in wb.sheetnames:
    ws = wb[sheet]
    rows = list(ws.iter_rows(values_only=True))
    if rows:
        headers = [str(h).strip() if h else '' for h in rows[0]]
        print(f'Sheet: {sheet}, Columns: {headers}')
        for row in rows[1:6]:
            print([str(c)[:80] if c else '' for c in row])
" "<framework-file>"

Adapt column mapping based on detected framework:

• CCMv4: Control ID, Control Domain, Control Title, Control Specification
• NIST 800-53: Control Identifier, Control Family, Control Name, Control Description
• CIS: Recommendation #, Section, Title, Description, Level
• ISO 27001: Clause, Control, Objective, Implementation Guidance

For .json files:

import json
data = json.load(open("<framework-file>"))
# Detect structure and extract objectives

For .md files:

Parse markdown headers and tables to extract framework objectives.

Step 2: Build Normalized framework_objectives[]

Regardless of source format, produce a normalized array where every objective has:

{
  "id": "IAM-01",
  "domain": "Identity & Access Management",
  "title": "Identity and Access Management Policy and Procedures",
  "specification": "Establish, document, approve, communicate, apply, evaluate...",
  "keywords": ["access", "identity", "authentication", "policy"]
}

Keyword extraction rules

Extract keywords from the specification text to aid downstream matching:

• Domain-specific terms (access, encryption, network, logging, etc.)
• Action verbs (restrict, monitor, audit, enforce, validate, protect)
• AWS-relevant terms (key management, multi-factor, least privilege, classification)
• De-duplicate and lowercase
• Max 10 keywords per objective — pick the most specific, not generic

Step 3: CCMv4 Built-in Fallback

If framework is CCMv4 but no xlsx is parseable, use this built-in domain reference:

NEVER invent control IDs outside these ranges.

When using built-in fallback, each objective gets:

• id: from the range (e.g., "IAM-01")
• domain: from the table above
• title: domain-level title (enriched if xlsx provided partial data)
• specification: domain-level specification (may be minimal if no xlsx)
• keywords: derived from domain name

Step 4: Write Output

Framework Name Rules (CRITICAL for output titles)

The framework.name field flows into ALL downstream output titles (e.g., "CSA CCMv4 Control Mapping — {service}", "NIST 800-53 Coverage Matrix", "Threat Model Coverage for MITRE ATT&CK"). Set it using these rules:

Rule: If the customer provides a file with a recognizable framework name in its content (headers, sheet names, or first-row data), prefer that over filename-based detection. For example, a file named security-controls.xlsx whose first column header is "NIST Control ID" should produce framework.name = "NIST 800-53".

Rule: If the file cannot be classified into any known framework, set framework.name = "Custom Framework". Never leave it empty or null.

Write .service-approval/<slug>/04-map/map-framework-parsed.json:

{
  "schema_version": "1.0",
  "framework": {
    "name": "CSA CCMv4",
    "version": "4.0",
    "source_file": "<path or 'built-in'>",
    "total_objectives": 197
  },
  "framework_objectives": [
    {
      "id": "A&A-01",
      "domain": "Audit & Assurance",
      "title": "Audit and Assurance Policy and Procedures",
      "specification": "...",
      "keywords": ["audit", "assurance", "policy", "compliance"]
    }
  ]
}

Schema rules:

• framework MUST be an object with keys: name, version, source_file, total_objectives
• framework_objectives MUST be a non-empty array
• Every objective MUST have: id, domain, title, specification, keywords
• total_objectives MUST equal len(framework_objectives)
• Objectives MUST be sorted by id (alphabetical)

Validate Output

Output validation runs automatically via PostToolUse hook (validate_state.py Check S10).

Print Summary

Map (Parse Framework) complete:
  Framework: {name} v{version}
  Source: {source_file}
  Objectives: {total_objectives}
  Domains: {count unique domains}
  Output: .service-approval/<slug>/04-map/map-framework-parsed.json