iso27001-sdlc

What this skill does

# ISO 27001:2022 Software Development Compliance Scanner

Scans a repository and produces a compliance gap report against the
ISO 27001:2022 Annex A software development controls (8.4, 8.25–8.33).

## Before you start

Read `references/controls.md` — it contains the per-control scoring rules,
example fix suggestions, and the mapping from evidence to status.

For 8.28 (Secure Coding) checks, also read `references/secure-coding-patterns.md`
which contains the per-language/framework lookup tables for libraries, config
locations, and unsafe code patterns.

## Architecture: two-phase scan → score

The skill separates evidence collection (deterministic) from compliance
scoring (judgment-based). This eliminates inconsistency where the same file
gets assessed differently for different controls.

**Phase 1 — Scan** runs `scripts/scan_repo.py` to collect all file evidence
into a single JSON structure. This is the only phase that touches the filesystem.

**Phase 2 — Score** reads the JSON evidence and applies the scoring rules from
`references/controls.md` to produce the markdown report. Evidence is mapped to
controls, not re-discovered per control.

## Phase 1: Collect evidence

Run the scanning script:

```bash
python /path/to/skill/scripts/scan_repo.py /path/to/repo --output /tmp/iso27001-evidence.json
```

The script indexes the entire repo and produces structured evidence covering:
file pattern matches, linter configs, security analysis tools, faker/synthetic
data libraries, hardcoded secret patterns, .gitignore checks, CI/CD config
analysis, ADR security content, security test files, language/container/IaC
detection, and monorepo detection.

Review the scan summary printed to stderr. If the repo is a monorepo (the
script detects this), see the Monorepo Handling section below before proceeding.

If the script fails or the repo is not locally available, fall back to manual
scanning: use `find`, `grep`, and `cat` to collect the same evidence described
in `references/controls.md`. The script is a convenience, not a hard dependency.

## Phase 2: Score and report

Read the evidence JSON produced by Phase 1. For each of the 10 core controls
(8.4, 8.25, 8.26, 8.27, 8.28, 8.29, 8.30, 8.31, 8.32, 8.33), apply the
scoring rules in `references/controls.md`.

The evidence JSON maps to controls like this:

| Evidence key | Used by controls |
|---|---|
| `file_evidence.codeowners` | 8.4, 8.32 |
| `file_evidence.pr_template`, `pr_template_security` | 8.25, 8.32 |
| `file_evidence.issue_template` | 8.25, 8.26 |
| `file_evidence.security_policy` | 8.25 |
| `architecture_security`, `adr_findings` | 8.27 |
| `file_evidence.threat_model` | 8.27 |
| `linter_evidence`, `security_analysis` | 8.28 |
| `secrets_findings`, `env_gitignore` | 8.28 |
| `file_evidence.lockfiles`, `file_evidence.dependency_scanning_config` | 8.28 |
| `secure_coding_practices.secure_coding_deps.input_validation` | 8.28, 8.26 |
| `secure_coding_practices.secure_coding_deps.authentication` | 8.28 |
| `secure_coding_practices.secure_coding_deps.password_hashing` | 8.28 |
| `secure_coding_practices.secure_coding_deps.security_headers` | 8.28 |
| `secure_coding_practices.secure_coding_deps.rate_limiting` | 8.28 |
| `secure_coding_practices.secure_coding_deps.sanitization` | 8.28 |
| `secure_coding_practices.secure_coding_deps.orm` | 8.28 |
| `secure_coding_practices.secure_coding_deps.structured_logging` | 8.28, supporting 8.16 |
| `secure_coding_practices.source_patterns.unsafe_functions` | 8.28 |
| `secure_coding_practices.source_patterns.raw_sql` | 8.28 |
| `secure_coding_practices.source_patterns.deprecated_crypto` | 8.28 |
| `secure_coding_practices.source_patterns.xss_template_escapes` | 8.28 |
| `secure_coding_practices.source_patterns.insecure_cors` | 8.28 |
| `secure_coding_practices.source_patterns.insecure_config` | 8.28 |
| `secure_coding_practices.csrf_evidence` | 8.28 |
| `secure_coding_practices.sbom_tooling` | 8.28, supporting 8.8 |
| `ci_evidence.security_jobs` | 8.25, 8.28, 8.29 |
| `security_test_files` | 8.29 |
| `file_evidence.env_specific_configs`, `file_evidence.env_dirs` | 8.31 |
| `file_evidence.changelog`, `file_evidence.commitlint_config` | 8.32 |
| `faker_evidence`, `file_evidence.test_fixtures_dirs` | 8.33 |

When a single piece of evidence is relevant to multiple controls, reference
it consistently — do not re-assess or describe it differently in each section.
Example: if CI has CodeQL configured, that's SAST evidence for 8.29, a
security gate for 8.25, and supporting evidence for 8.28. State the fact once,
reference it in each control.

After scoring core controls, do a lighter pass on supporting controls
(5.8, 8.7, 8.8, 8.9, 8.16) — present if found, flag if absent, but don't
fail the report over them.

### Handling absent infrastructure

If no CI/CD configuration is found, do not attempt CI-related checks.
Instead flag CI/CD as an analysis gap and include this guidance:

> ISO 27001:2022 expects automated security controls integrated into the
> build and deployment pipeline: static analysis (SAST), dependency scanning
> (SCA), and approval gates before production deployment. Without CI/CD
> configuration in the repository, these controls cannot be verified. The
> organization should document its CI/CD approach and ensure security scans
> are mandatory pipeline stages.

The same principle applies to any absent infrastructure — flag the gap,
explain the ISO requirement, move on.

## Report format

Produce a single markdown report. Use this structure:

```markdown
# ISO 27001:2022 Software Development Compliance Report

**Repository:** <name>
**Scan date:** <date>
**Languages/frameworks:** <detected>
**CI/CD system:** <detected or "None detected">
**Repository type:** <single project / monorepo with N sub-projects>

## Executive Summary

<Lead with the highest-risk gap. State overall posture. Name the #1 priority action.>

**Overall posture:** <STRONG / MODERATE / WEAK / CRITICAL GAPS>

| Status | Count |
|--------|-------|
| PASS | X |
| WARNING | X |
| FAIL | X |
| MANUAL REVIEW NEEDED | X |
| NOT APPLICABLE | X |

## Detailed Findings

### 8.X — <Control Name>

**Status:** PASS / FAIL / WARNING / NOT APPLICABLE / MANUAL REVIEW NEEDED

**What this control requires:**
<1-2 sentences from the control intent in controls.md>

**Evidence found:**
- <file path or config with brief description>

**Gaps identified:**
- <what is missing>

**Recommended actions:**
- <concrete fix suggestion from controls.md>
- <if templates would help: "A template for <X> can be generated on request.">

---

[repeat for each of the 10 controls]

## Supporting Controls

| Control | Status | Notes |
|---------|--------|-------|
| 5.8 — Info security in project mgmt | ... | ... |
| 8.8 — Vulnerability management | ... | ... |
| ... | ... | ... |

## Next Steps

<Top 3-5 prioritized actions. Be specific: "Add a .bandit config for Python
SAST" not "improve security testing.">

## Appendix: Analysis Limitations

<What the scan could not verify: platform-level access controls, process
adherence, training records, contractual controls, etc.>
```

Keep the report concise. For large repos, summarize evidence per control
(e.g., "14 workflow files found, 3 contain security scanning stages")
rather than listing every file. Only list individual files when they're
notable (secrets found, key configs present/absent).

## Example control output

This example shows the expected quality bar for a single control finding:

```markdown
### 8.28 — Secure Coding

**Status:** WARNING

**What this control requires:**
Apply secure coding principles to prevent common vulnerabilities. Enforce
coding standards, use static analysis, manage dependencies securely, and
prevent hardcoded secrets.

**Evidence found:**
- `.eslintrc.json` — ESLint configured but no security plugin (`eslint-plugin-security` absent)
- `package-lock.json` — dependency lock file present
- `.github/dependabot.yml` — automated dependency updates configured
- `.