fedramp-poam-quality-check - SKILL.md Agent Skill

name: FedRAMP POAM Quality Check slug: compliance-fedramp-validator description: Validates FedRAMP Plan of Action and Milestones (POAM) files for structural integrity, naming conventions, deduplication, and cross-sheet consistency capabilities:

Header and format validation
Naming convention compliance checks
Duplicate entry detection
Cross-sheet consistency validation
Remediation timeline verification inputs:
name: poam_tsv type: file format: TSV (tab-separated values) description: FedRAMP POAM export or OSCAL-derived tabular format
name: naming_convention type: json description: Schema defining valid field names, formats, and constraint rules optional: true outputs:
name: findings type: json schema: "{"errors": [{"row": int, "field": str, "issue": str, "severity": str}], "warnings": [...], "stats": {"total_rows": int, "duplicates": int, "missing_required": int}}"
name: fix_suggestions type: markdown description: Human-readable remediation guidance ranked by severity keywords:
fedramp
poam
quality-check
validation
vulnerability-tracking
compliance version: 1.0.0 owner: william@cognitive-toolworks.com license: CC0-1.0 security:
No credential handling
File read-only operations
No external API calls
Local processing only links:
title: FedRAMP OSCAL POA&M Documentation url: https://automate.fedramp.gov/documentation/poam/ accessed: 2025-10-25T21:04:34-04:00
title: FedRAMP POA&M Template Completion Guide url: https://www.fedramp.gov/assets/resources/documents/CSP_POAM_Template_Completion_Guide.pdf accessed: 2025-10-25T21:04:34-04:00
title: NIST SP 800-37 Rev. 2 - Risk Management Framework url: https://csrc.nist.gov/pubs/sp/800/37/r2/final accessed: 2025-10-25T21:04:34-04:00
title: FedRAMP Vulnerability Scanning Requirements url: https://www.fedramp.gov/resources/documents/CSP_Vulnerability_Scanning_Requirements.pdf accessed: 2025-10-25T21:04:34-04:00

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:

Input availability:
- poam_tsv file exists and is readable
- File size < 10 MB (sanity check)
- At least one header row present
Time context:
- Compute NOW_ET using NIST time.gov semantics (America/New_York, ISO-8601)
- Current timestamp: 2025-10-25T21:04:34-04:00
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
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

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
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}

Output (JSON):

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

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

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}
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)
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
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/
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

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)
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
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
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)

Comprehensive markdown report:

## 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):

{
  "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)

# 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