map-controls

# Map Controls Run an interactive mapping session for a control file. Walks through each unmapped requirement, finds candidate rules via cross-framework search and AI suggestions, lets the author select rules, and writes them back to the control file. This skill orchestrates `/inspect-control` for setup and `/map-requirement` logic for each requirement. ## Tool Strategy This skill uses `mcp__content-mcp__*` tools when available (preferred — deterministic, structured results). When the MCP server is not configured, fall back to filesystem-based alternatives noted as **Fallback** in each step. See `.claude/skills/shared/mcp_fallbacks.md` for detailed fallback procedures. The skill must complete successfully either way. **Without MCP server**: Cross-framework similarity search is unavailable. Candidate rules will be found by keyword search only, which may miss semantically similar but differently-worded requirements. **Arguments**: $ARGUMENTS — format: `<control_id> [--product <product_id>] [--policy <path>]` Examples: - `/map-controls anssi --product rhel9` - `/map-controls srg_gpos --product rhel10` - `/map-controls hipaa` - `/map-controls anssi --product rhel9 --policy security_policies/anssi_2.md` ## Phase 1: Setup and Validation 1. **Parse arguments**: Extract `control_id`, optional `--product`, and optional `--policy` from `$ARGUMENTS`. 2. **Load control stats**: Call `mcp__content-mcp__get_control_stats` with `control_id`. - If not found, call `mcp__content-mcp__list_controls` and present options via `AskUserQuestion`. - **Fallback**: Read `controls/<control_id>.yml` or `products/**/controls/<control_id>.yml`. Count requirements by status manually. List controls with `ls controls/*.yml` and `ls products/*/controls/*.yml`. 3. **If no `--product` specified**, discover available products and ask user via `AskUserQuestion`: - Run `ls products/` (or call `mcp__content-mcp__list_products`) to get the list of available products - "Which product are you mapping rules for?" - Options: present the most common products from the discovered list + Other 4. **Check build artifacts**: Call `mcp__content-mcp__list_built_products`. - If the target product is NOT in the built list, ask the user via `AskUserQuestion`: - "Product '{product}' has not been built yet. Rule search works best with build artifacts (expanded Jinja templates). Build it now?" - Options: - "Yes, build now (Recommended)" — description: "Runs `/build-product {product} --datastream-only` before starting the mapping session" - "No, continue without build" — description: "Rule search will use raw source files, which may miss some rules due to Jinja template parsing errors" - If user chooses to build, invoke the `build-product` skill: `Skill(skill="build-product", args="{product} --datastream-only")`. Wait for the build to complete before continuing. - **Fallback**: Check if `build/{product}/rules/` directory exists. If not, offer the build prompt above. 5. **Report summary**: ``` ## Control File: {title} ({control_id}) | Status | Count | |-----------|-------| | Total | {total} | | Mapped | {mapped} | | Unmapped | {unmapped} | ``` Show the `by_status` breakdown, only including statuses with non-zero counts. 6. **If no `--policy` specified**, inform the user: > **Tip**: You can enrich mapping with the original security policy document by adding `--policy <path>` (supports PDF, Markdown, HTML). This provides full policy context for each requirement, improving cross-framework matching accuracy. 7. **Get work queue**: Call `mcp__content-mcp__list_unmapped_requirements` with `control_id`. **Fallback**: Read the control YAML and filter requirements where `status` is `pending` or `rules:` is empty/missing. 8. **Ask user scope** via `AskUserQuestion`: - "Which requirements do you want to work on?" - Options: - "Unmapped only ({N} requirements)" — work through the pending/unmapped queue - "All requirements ({total})" — review every requirement including already-mapped ones - "Specific requirement IDs" — let user type specific IDs ## Phase 2: Per-Requirement Mapping Loop **Note**: Do NOT call `get_control_rule_index` here — it returns a massive payload (1.6MB+) that wastes context. The per-requirement `find_similar_requirements` call in Step 2b already provides cross-framework discovery for each requirement individually. For each requirement in the selected work queue, execute the mapping workflow. This follows the same logic as `/map-requirement` but in batch. ### For each requirement: #### Step 2a: Present the Requirement Display: ``` --- ### [{current}/{total}] Requirement: {requirement_id} **Title**: {title} **Description**: {description} **Current status**: {status} **Current rules**: {rules or "none"} --- ``` If `--policy` was provided: 1. **Infer document type** from the file extension (`.md` → `markdown`, `.pdf` → `pdf`, `.html` → `html`, otherwise → `text`) 2. Call `mcp__content-mcp__parse_policy_document` with `source`, `document_type`, and `requirement_id` for the current requirement. **Fallback**: For markdown/text, read the file and search for the requirement ID. For PDF, inform user that PDF parsing requires the MCP server. 3. If sections returned, display the policy context: ``` ### Policy Context (from {policy_path}) **{section_title}** {section_content} ``` 4. Store the combined section text as `policy_text` for use in Step 2b #### Step 2b: Cross-Framework Search Call `mcp__content-mcp__find_similar_requirements` with: - `requirement_text`: if `policy_text` is available, use it; otherwise use the requirement's title + " " + description - `exclude_control_id`: current control_id - `max_results`: 10 **Fallback**: Extract 3-5 key terms from the requirement text. Use `Grep` to search for each term across `controls/*.yml` and `products/*/controls/*.yml`. Read matched requirements to extract their `rules:` lists. If results found, present grouped by framework: ``` Similar requirements in other frameworks: - [{control_id}] {req_id}: "{title}" → rules: {rules} ``` Extract the union of all rules as cross-framework candidates. #### Step 2c: Rule Search in Build Artifacts Search for candidate rules using rendered build artifacts (Jinja-expanded, product-specific): 1. Extract 3-5 key terms from the requirement title and description. 2. For each key term, call `mcp__content-mcp__search_rendered_content` with: - `query`: the key term - `product`: the target product from Phase 1 - `limit`: 15 - **Fallback**: If the product is not built, use `Grep` to search for key terms in `rule.yml` files under `linux_os/guide/` and `applications/`. This may miss rules with Jinja-templated descriptions. 3. Deduplicate results across all term searches. Combine with cross-framework candidates from Step 2b. 4. For each candidate rule, use `mcp__content-mcp__get_rendered_rule` (or `get_rule_details`) to read its title and description. Reason about which rules best match the requirement semantically. 5. Present the top candidates in a table: ``` ### Rule Candidates | Rule ID | Title | Source | Reasoning | |---------|-------|--------|-----------| | {rule_id} | {title} | cross-ref / search | {why it matches} | ``` #### Step 2d: Product Availability Check Since `search_rendered_content` only returns rules present in the target product's build, all search results are already confirmed available. For cross-framework candidates (from Step 2b) that did NOT appear in the rendered search, call `mcp__content-mcp__get_rule_product_availability` to verify availability. **Fallback**: Check each rule's `rule.yml` for `cce@<product>` entries and grep for the rule ID in target product profiles/controls. Flag rules NOT available for the target product. Assess portability: - Templated rules are likely portable - Check platform constraints if present #### Step 2e: Author Decision 1. Build unified candidate list: combine cross-framework and AI suggestions, deduplicated, sorted by confidence. 2. Use `AskUserQuestion` with `multiSelect: true`: - "Select rules for '{requirement_id}: {title}'" - Options: top candidates (up to 4), with confidence and source info - If more than 4 candidates, present top 3 + "Show more candidates" 3. Use a separate `AskUserQuestion`: - "How should this requirement be marked?" - Options: - "Automated" — fully covered - "Partially automated" — partially covered - "Not applicable" — doesn't apply - "Create new rule" — will be collected for gap analysis - "Skip for now" #### Step 2f: Write Selection - **If rules selected**: Call `mcp__content-mcp__update_requirement_rules` with `control_id`, `requirement_id`, `rules`, and appropriate `status`. **Fallback**: Find and edit the requirement's YAML file directly using `Edit` tool. - **If not applicable**: Call `mcp__content-mcp__update_requirement_rules` with empty rules and `status="not_applicable"`. **Fallback**: Edit the requirement's YAML file to set `status: not_applicable` and `rules: []`. - **If create new rule**: Add to the "new rules needed" list for Phase 3. - **If skipped**: Record as skipped, move to next. Track all changes for the final report. ## Phase 3: Gap Analysis For requirements where the author chose "Create new rule": 1. For each gap requirement, use LLM analysis to: - Decompose the requirement into atomic checks (one config change per rule) - Suggest rule IDs following naming conventions (lowercase, underscores) - Suggest which template might apply (call `mcp__content-mcp__list_templates` and match; **Fallback**: `ls shared/templates/`) - Suggest severity based on the requirement 2. Present the decomposition: ``` ### Gap: {requirement_id} — {title} This requirement could be covered by: 1. {suggested_rule_id} (template: {template_name}) — {description} 2. {suggested_rule_id} (template: {template_name}) — {description} ``` 3. Ask user which rules to create via `AskUserQuestion`. 4. For each approved new rule, tell the user to run `/create-rule <rule_id>` with the suggested parameters after this session completes. ## Phase 4: Final Report Present a complete summary of the mapping session: ``` ## Mapping Session Complete **Control file**: {control_id} ({title}) **Target product**: {product} ### Changes Made - {X} requirements mapped to existing rules - {Y} requirements marked not applicable - {Z} requirements skipped ### Rules Added | Requirement | Rules | Status | |-------------|-------|--------| | {req_id} | {rules} | automated | | ... | ... | ... | ### New Rules Needed | Requirement | Suggested Rules | Template | |-------------|----------------|----------| | {req_id} | {rule_ids} | {template} | ### Updated Stats ``` Call `mcp__content-mcp__get_control_stats` again to show the updated coverage. **Fallback**: Re-read the control YAML and recount requirements by status. ``` | Status | Before | After | |----------|--------|-------| | Mapped | {before} | {after} | | Unmapped | {before} | {after} | | Coverage | {before}% | {after}% | ``` ``` ### Next Steps 1. Review changes: `git diff controls/` 2. Build product: `/build-product {product}` 3. Create new rules: `/create-rule <rule_id>` for each gap 4. Test rules: `/test-rule <rule_id>` 5. Draft PR: `/draft-pr` ``` ## Important Notes - **The `update_requirement_rules` tool replaces existing rules** — if a requirement already has rules and the author wants to add more, include the existing rules in the selection. - **AI suggestions require API key** — if `suggest_rule_mappings` fails, fall back to cross-framework search only. - **Large control files** (e.g., srg_gpos with 300+ requirements) — consider processing in batches. After every 10 requirements, ask if the user wants to continue or pause. - **Track before/after stats** — call `get_control_stats` at the start and end to show progress. - **Don't overwhelm the user** — if cross-framework search and AI both return many candidates, focus on the top 5-10 with highest confidence.