williamzujkowski/FedRAMP POAM Quality Check

Purpose & When-To-Use

Use this skill when you need to validate a FedRAMP Plan of Action and Milestones (POAM) file before submission or continuous monitoring updates. The POAM tracks system weaknesses and deficiencies with corrective actions and timelines according to FedRAMP requirements (accessed 2025-10-25T21:04:34-04:00: https://www.fedramp.gov/assets/resources/documents/CSP_POAM_Template_Completion_Guide.pdf).

Trigger conditions:

• Pre-submission quality gates for FedRAMP POAM deliverables
• Continuous monitoring validation before AO submission
• Post-assessment cleanup to ensure data integrity
• Integration checks for OSCAL-to-TSV conversions
• Duplicate entry detection across Open/Closed sheets

Pre-Checks

Required validations before proceeding:

1. Input availability:

• poam_tsv file exists and is readable
• File size < 10 MB (sanity check)
• At least one header row present

1. Time context:

• Compute NOW_ET using NIST time.gov semantics (America/New_York, ISO-8601)
• Current timestamp: 2025-10-25T21:04:34-04:00

1. Schema availability:

• If naming_convention provided, validate JSON schema structure
• Required keys: required_fields, date_format, severity_levels
• Default to FedRAMP standard if not provided

1. Encoding check:

• Verify UTF-8 or ASCII encoding
• Tab-delimited structure (not comma/pipe/other)

Abort conditions:

• File unreadable or corrupted
• No recognizable header row
• Encoding errors preventing parse

Procedure

Tier 1: Header & Format Sanity (≤2k tokens)

Goal: Fast validation for 80% of common issues

1. Parse header row:

• Extract column names
• Verify presence of core required fields:
• POA&M Item ID, Control Identifier, Weakness Description
• Risk Level (or Severity), Scheduled Completion Date, Status

1. Row-level format checks:

• Count total rows (Open + Closed if multi-sheet)
• Detect missing required fields (empty cells in required columns)
• Flag malformed dates (must match YYYY-MM-DD or MM/DD/YYYY)
• Check severity values: must be in {High, Moderate, Low, Informational}

1. Output (JSON):

json { "errors": [ {"row": 12, "field": "Scheduled Completion Date", "issue": "Invalid date format", "severity": "error"} ], "warnings": [], "stats": {"total_rows": 47, "duplicates": 0, "missing_required": 3} }

1. Decision rule:

• If errors > 10% of rows OR missing_required > 5, stop and report
• Else proceed to T2

Token budget: ≤2k

Tier 2: Naming Convention & Deduplication (≤6k tokens)

Goal: Enforce naming standards and detect duplicates

1. Apply naming convention schema:

• Validate POA&M Item ID format (e.g., POAM-YYYY-### or custom regex)
• Check Control Identifier against NIST 800-53 rev4/rev5 catalog
• Verify Status values: {Open, In Progress, Completed, Risk Accepted}

1. Deduplication logic:

• Compute hash of (Control Identifier, Weakness Description, Resource)
• Flag exact duplicates across Open/Closed sheets
• Warn on near-duplicates (80%+ text similarity in Weakness Description)

1. Timeline validation (FedRAMP requirements):

• High severity: remediation ≤ 30 days from discovery (accessed 2025-10-25T21:04:34-04:00: https://www.fedramp.gov/resources/documents/CSP_Vulnerability_Scanning_Requirements.pdf)
• Moderate: ≤ 90 days
• Low: ≤ 180 days
• Flag overdue items with current NOW_ET comparison

1. Sources cited:

• FedRAMP POA&M Template Completion Guide (accessed 2025-10-25T21:04:34-04:00): https://www.fedramp.gov/assets/resources/documents/CSP_POAM_Template_Completion_Guide.pdf
• FedRAMP Vulnerability Scanning Requirements (accessed 2025-10-25T21:04:34-04:00): https://www.fedramp.gov/resources/documents/CSP_Vulnerability_Scanning_Requirements.pdf
• NIST SP 800-37 Rev. 2 (accessed 2025-10-25T21:04:34-04:00): https://csrc.nist.gov/pubs/sp/800/37/r2/final
• FedRAMP OSCAL POA&M Documentation (accessed 2025-10-25T21:04:34-04:00): https://automate.fedramp.gov/documentation/poam/

1. Enhanced output:

• Add warnings for near-duplicates and overdue timelines
• Populate duplicates count in stats
• Generate markdown fix suggestions prioritized by severity

Token budget: ≤6k

Tier 3: Cross-Sheet Consistency (≤12k tokens)

Goal: Deep validation across Open/Closed sheets and logical integrity

1. Sheet relationship checks:

• Verify no item appears in both Open and Closed sheets
• Validate Closed items have Completion Date and Status = Completed
• Check for reopened items (same ID moved from Closed → Open)

1. Risk scoring consistency:

• If CVSS scores present, validate against declared Risk Level
• Cross-reference Weakness Description with known CVE/CWE patterns
• Flag discrepancies between narrative severity and numeric scores

1. Milestone progression:

• For multi-milestone POAMs, verify dates are sequential
• Check that Original Detection Date ≤ Scheduled Completion Date
• Validate Resources Required field is populated for High/Moderate items

1. Rationale generation:

• For each error/warning, provide context and remediation steps
• Link to relevant sections of FedRAMP/NIST guidance
• Estimate compliance risk (blocker vs. advisory)

1. Comprehensive markdown report:

markdown ## Critical Issues (3)

• Row 12: Invalid completion date (blocks submission)
• Row 23: Duplicate weakness (merge required)

## Warnings (7)

• Row 8: Timeline exceeds FedRAMP requirement (High: 30 days)

## Recommendations

• Update naming convention to include fiscal year prefix
• Consider automated CVE enrichment for weakness descriptions

Token budget: ≤12k

Decision Rules

Ambiguity thresholds:

• Exact duplicate: 100% match on (Control ID, Weakness, Resource)
• Near-duplicate: ≥80% cosine similarity on Weakness Description text
• Overdue tolerance: Grace period of 7 calendar days beyond FedRAMP timeline

Abort/stop conditions:

• File parse failure → stop at Pre-Checks
• Errors > 10% rows → stop after T1, report findings
• Missing schema keys → use FedRAMP defaults, log warning

Escalation triggers:

• Critical errors (missing required fields, invalid dates) → halt progression
• Warnings only → continue to T3 if requested

Output Contract

Primary output (findings.json):

json
{
  "errors": [
    {
      "row": 12,
      "field": "Scheduled Completion Date",
      "issue": "Invalid date format (expected YYYY-MM-DD)",
      "severity": "error"
    }
  ],
  "warnings": [
    {
      "row": 8,
      "field": "Risk Level",
      "issue": "High-severity item overdue by 15 days",
      "severity": "warning"
    }
  ],
  "stats": {
    "total_rows": 47,
    "duplicates": 2,
    "missing_required": 3,
    "overdue_high": 1,
    "overdue_moderate": 4
  }
}

Secondary output (fix_suggestions.md):

• Markdown-formatted remediation guidance
• Grouped by severity: Critical → High → Medium → Low
• Includes row numbers, field names, and specific correction steps
• Links to authoritative sources for each issue type

Required fields in all outputs:

• timestamp: ISO-8601 Eastern Time (NOW_ET)
• skill_version: "1.0.0"
• input_file: original filename

Examples

Example 1: Basic T1 validation (≤30 lines)

python
# Input: poam_tsv = "fedramp_poam_2025.tsv"

findings = {
  "errors": [
    {"row": 5, "field": "POA&M Item ID", "issue": "Missing"},
    {"row": 12, "field": "Date", "issue": "Invalid '13/45/2025'"}
  ],
  "warnings": [
    {"row": 8, "issue": "High overdue 15d"}
  ],
  "stats": {"total_rows": 47, "duplicates": 2}
}

fix_suggestions = """
## Critical (2)
- Row 5: Add POA&M Item ID (POAM-2025-NNN)
- Row 12: Fix date (YYYY-MM-DD)

## Warnings (1)
- Row 8: High past 30-day window
"""

import json
print(json.dumps(findings))
print(fix_suggestions)
# Output: JSON findings + markdown suggestions

Quality Gates

Token budgets (mandatory):

• T1: ≤2k tokens (header + format checks)
• T2: ≤6k tokens (naming + deduplication + 2-4 sources)
• T3: ≤12k tokens (cross-sheet + rationale generation)

Safety checks:

• No external network calls (file processing only)
• No credential handling or sensitive data exposure
• Read-only operations on input files
• Validate file paths are within expected directories

Auditability:

• Log all validation steps with timestamps
• Preserve original input (no in-place modifications)
• Link every error/warning to specific source requirement
• Include skill version in all outputs

Determinism:

• Same input → same output (no random sampling)
• Consistent hash functions for duplicate detection
• Fixed threshold values (no dynamic adjustment)
• Reproducible similarity scoring (cosine/Levenshtein)

Performance targets:

• T1: < 5 seconds for files ≤1000 rows
• T2: < 15 seconds including duplicate detection
• T3: < 30 seconds for full cross-sheet analysis

Resources

Official FedRAMP guidance:

• FedRAMP POA&M Template Completion Guide: https://www.fedramp.gov/assets/resources/documents/CSP_POAM_Template_Completion_Guide.pdf
• FedRAMP OSCAL POA&M Documentation: https://automate.fedramp.gov/documentation/poam/
• FedRAMP Vulnerability Scanning Requirements: https://www.fedramp.gov/resources/documents/CSP_Vulnerability_Scanning_Requirements.pdf

NIST references:

• NIST SP 800-37 Rev. 2 (Risk Management Framework): https://csrc.nist.gov/pubs/sp/800/37/r2/final
• NIST SP 800-53 Rev. 5 (Security Controls): https://csrc.nist.gov/pubs/sp/800/53/r5/upd1/final

OSCAL resources:

• OSCAL POA&M Model: https://pages.nist.gov/OSCAL/concepts/layer/assessment/poam/
• FedRAMP OSCAL Baselines: https://github.com/GSA/fedramp-automation

Helper tools (linked in resources/):

• naming_convention_schema.json - Default FedRAMP field validation rules
• similarity_thresholds.yaml - Tunable deduplication parameters