Infra Auditor

Infrastructure Auditor Skill

Your responsibility is to provide non-destructive observability into infrastructure state, health, security posture, and cost without making any modifications.

Based on the corthos audit-first pattern: INSPECT → ANALYZE → PRESENT → APPROVE → EXECUTE → VERIFY → REPORT

IMPORTANT: Execute checks efficiently

• Most checks should complete in <10 seconds
• Full audit should complete in <30 seconds
• Use caching where appropriate
• Fail fast on critical issues
• Structured output format

1. Parse Parameters

   • Determine environment (test or prod)
   • Determine check type (default: config-valid)
   • Validate environment exists
   • Load configuration

2. Select Workflow File

   • Based on check-type, load appropriate workflow:
     • config-valid → workflow/config-valid.md
     • iam-health → workflow/iam-health.md
     • drift → workflow/drift.md
     • cost → workflow/cost.md
     • security → workflow/security.md
     • full → workflow/full.md

3. Execute Workflow

   • Follow workflow instructions from selected file
   • Execute read-only checks via scripts
   • Collect findings
   • Calculate metrics
   • Generate recommendations

4. Collect Audit Data

   • Format findings in structured output
   • Include status summary (passing/warnings/failures)
   • List checks performed
   • Calculate metrics (resources, drift, cost, etc.)
   • Categorize recommendations by priority
   • Include timestamp and duration

5. Generate Standardized Report

   • Invoke docs-manage-audit skill to create dual-format report
   • Pass collected audit data in standardized schema format
   • Generate both README.md and audit.json files
   • Store in logs/infrastructure/audits/{env}/

6. Return Results

   • Output structured report summary
   • Exit with appropriate status code:
     • 0: All checks passed
     • 1: Warnings found
     • 2: Failures found

Checks:

• Terraform syntax validity
• Required variables defined
• Backend configuration valid
• Provider configuration valid
• Module references correct

Script: scripts/audit-config.sh

IAM Health (iam-health)

Duration: ~3-5 seconds Purpose: Verify IAM users, roles, and permissions

Checks:

• Deploy user exists and has valid credentials
• Required IAM roles present
• Service roles attached to resources
• No unused IAM resources
• Permissions aligned with least privilege

Script: scripts/audit-iam.sh

Drift Detection (drift)

Duration: ~5-10 seconds Purpose: Detect configuration drift between Terraform and AWS

Checks:

• Run terraform plan -detailed-exitcode
• Identify resources modified outside Terraform
• Detect manual changes to tags, configuration
• Show what differs from expected state

Script: scripts/audit-drift.sh

Cost Analysis (cost)

Duration: ~3-5 seconds Purpose: Analyze infrastructure cost and identify anomalies

Checks:

• Estimated monthly cost
• Cost by resource type
• Cost trends (if historical data available)
• Cost optimization opportunities
• Budget compliance (if configured)

Script: scripts/audit-cost.sh

Security Posture (security)

Duration: ~5-7 seconds Purpose: Security and compliance checks

Checks:

• Open security groups
• Unencrypted resources (S3, RDS, EBS)
• Public S3 buckets
• IAM overpermissions
• CIS benchmark compliance
• Resource tagging compliance

Script: scripts/audit-security.sh

Full Audit (full)

Duration: ~20-30 seconds Purpose: Comprehensive audit (all checks)

Executes all check types in sequence:

1. config-valid
2. iam-health
3. drift
4. security
5. cost

Aggregates results into single report.

Script: scripts/audit-full.sh

Report Storage Location:

• Base Directory: logs/infrastructure/audits/{env}/
• JSON Report: logs/infrastructure/audits/{env}/{timestamp}-{check-type}.json
• Markdown Report: logs/infrastructure/audits/{env}/{timestamp}-{check-type}.md

Timestamp Format: YYYYMMDD-HHMMSS (e.g., 20250105-143022)

Markdown Report Format:

# Audit Report: {ENV} Environment

**Check Type**: {check_type}
**Timestamp**: {ISO8601}
**Duration**: {duration}s
**Project**: {project-subsystem}

---

## Summary

**Duration:** {duration}s

### Status
- ✅ **Passing:** {passing_count}
- ⚠️  **Warnings:** {warning_count}
- ❌ **Failures:** {failure_count}

---

## Checks Performed

### {Status Icon} {Check Name}

{Details}

---

## Metrics

- **metric_name:** value

---

## Recommendations

### 🔴 Critical (Fix Immediately)
- {recommendation}

### 🟡 Important (Fix Soon)
- {recommendation}

### 🟢 Optimization (Consider)
- {recommendation}

---

**Report Files:**
- JSON: `logs/infrastructure/audits/{env}/{timestamp}-{check-type}.json`
- Markdown: `logs/infrastructure/audits/{env}/{timestamp}-{check-type}.md`

JSON Report Format:

{
  "audit": {
    "check_type": "{check_type}",
    "environment": "{env}",
    "timestamp": "{ISO8601}",
    "project": "{project-subsystem}",
    "status": "completed",
    "duration_seconds": {duration}
  },
  "summary": {
    "passing": {count},
    "warnings": {count},
    "failures": {count}
  },
  "checks": [
    {
      "name": "{check_name}",
      "status": "pass|warn|fail",
      "details": "{details}"
    }
  ],
  "metrics": {
    "metric_name": "value"
  },
  "recommendations": [
    {
      "priority": "critical|important|optimization",
      "recommendation": "{recommendation}"
    }
  ]
}

Status Icons:

• ✅ = Passed
• ⚠️ = Warning (non-critical)
• ❌ = Failed (critical)

Exit Codes:

• 0 = All checks passed
• 1 = Warnings found (non-critical)
• 2 = Failures found (critical issues)

After collecting audit data, invoke the docs-manage-audit skill to generate dual-format reports:

Skill(skill="docs-manage-audit")

Then provide the audit data in this format:

Use the docs-manage-audit skill to create infrastructure audit report with the following parameters:
{
  "operation": "create",
  "audit_type": "infrastructure",
  "check_type": "{check-type}",
  "environment": "{env}",
  "audit_data": {
    "audit": {
      "type": "infrastructure",
      "check_type": "{check-type}",
      "environment": "{env}",
      "project": "{project-subsystem}",
      "timestamp": "{ISO8601}",
      "duration_seconds": {duration},
      "auditor": {
        "plugin": "fractary-faber-cloud",
        "skill": "infra-auditor"
      },
      "audit_id": "{timestamp}-{check-type}"
    },
    "summary": {
      "overall_status": "pass|warning|error",
      "status_counts": {
        "passing": {passing_count},
        "warnings": {warning_count},
        "failures": {failure_count}
      },
      "exit_code": {0|1|2}
    },
    "findings": {
      "categories": [
        {
          "name": "{category}",
          "status": "pass|warning|error",
          "checks_performed": {count},
          "passing": {count},
          "warnings": {count},
          "failures": {count}
        }
      ],
      "by_severity": {
        "critical": [{finding}],
        "high": [{finding}],
        "medium": [{finding}],
        "low": [{finding}]
      }
    },
    "metrics": {
      "resource_count": {count}
    },
    "recommendations": [
      {
        "priority": "critical|high|medium|low",
        "category": "infrastructure",
        "recommendation": "{recommendation}"
      }
    ],
    "extensions": {
      "infrastructure": {
        "drift_detected": {boolean},
        "drift_resources": [{resources}],
        "cost_current": "{amount}",
        "security_issues": {count},
        "iam_issues": {count}
      }
    }
  },
  "output_path": "logs/infrastructure/audits/{env}/",
  "project_root": "{project-root}"
}

Finding Structure

Each finding should include:

{
  "id": "{unique-id}",
  "severity": "critical|high|medium|low",
  "category": "configuration|security|cost|drift|iam",
  "check": "{check-name}",
  "message": "{description}",
  "details": "{additional-context}",
  "resource": "{resource-identifier}",
  "remediation": "{how-to-fix}"
}

Mapping Infrastructure Checks to Schema

Overall Status Determination:

• pass = All checks passed (exit code 0)
• warning = Some warnings found (exit code 1)
• error = Some failures found (exit code 2)

Category Mapping:

• config-valid → "Configuration" category
• iam-health → "IAM" category
• drift → "Drift Detection" category
• cost → "Cost Optimization" category
• security → "Security" category
• full → Multiple categories

Severity Assignment:

• Critical security issues → critical
• Failed checks → high
• Warnings → medium
• Optimizations → low

docs-manage-audit Output

The skill will generate:

• README.md: Human-readable dashboard with status summary, findings by severity, metrics, and recommendations
• audit.json: Machine-readable structured data for automation and trending

Both files stored in logs/infrastructure/audits/{env}/{timestamp}-{check-type}.[md|json]

✅ COMPLETED: Infrastructure Audit
Environment: {env}
Check Type: {check_type}
Duration: {duration}s
Status: {passing/warnings/failures}
───────────────────────────────────────
Reports Generated:
- JSON: logs/infrastructure/audits/{env}/{timestamp}-{check-type}.json
- Markdown: logs/infrastructure/audits/{env}/{timestamp}-{check-type}.md

{Report summary}
Next: {Recommended action}

Important: All audit reports are timestamped and preserved for historical tracking and trend analysis.

Invoked before deployment to verify readiness:

infra-auditor --env=test --check=config-valid
infra-auditor --env=test --check=security

Block deployment if critical issues found.

Post-Deployment Validation

Invoked after deployment to verify success:

infra-auditor --env=test --check=full

Confirm all resources deployed correctly, no drift, security compliant.

Troubleshooting Preparation

Invoked before debugging to gather current state:

infra-auditor --env=prod --check=full

Provide complete state picture to infra-debugger.

Regular Health Monitoring

Scheduled or on-demand health checks:

infra-auditor --env=prod --check=drift
infra-auditor --env=prod --check=security
infra-auditor --env=prod --check=cost

Detect issues early before they become problems.

Your Primary Goal

Provide fast, non-destructive observability into infrastructure state, health, security, and cost. Generate actionable insights without ever modifying infrastructure. Enable confident deployments through pre/post-deployment verification.