ISO Sheriff

ISO 27001 readiness analyzer for codebases. A lightweight CLI tool that scans your repository and generates compliance reports, roadmaps, and evidence templates.

Features

• 🔍 Automated Scanning: Detects security controls, configurations, and best practices
• 📊 Comprehensive Reports: HTML and JSON reports with detailed findings
• 🗺️ Prioritized Roadmap: 30/60/90-day action plan with evidence requirements
• 📝 Evidence Templates: Auto-generates starter templates for missing documentation
• 🛠️ Extensible: Modular architecture for easy customization

Installation

npm install
npm run build

Or install globally:

npm install -g .

Usage

Basic Scan

iso-sheriff scan <path-to-repo>

This generates a JSON report by default in .iso-sheriff/report.json.

Generate All Reports

iso-sheriff scan <path> --html --json --roadmap --evidence-pack

Options

• --html: Generate HTML report (.iso-sheriff/report.html)
• --json: Generate JSON report (.iso-sheriff/report.json)
• --roadmap: Generate roadmap markdown (.iso-sheriff/roadmap.md)
• --evidence-pack: Generate evidence pack templates (.iso-sheriff/evidence-pack/)
• --serve [port]: Start a web server to view reports (default port: 27001)
• --tools: Enable optional tool integrations (gitleaks, semgrep, osv-scanner)

Example

# Scan a Next.js project
iso-sheriff scan ./my-app --html --roadmap --evidence-pack

# With optional security tools
iso-sheriff scan ./my-app --html --tools

# Start a web server to view reports
iso-sheriff scan ./my-app --html --serve
# Or specify a custom port
iso-sheriff scan ./my-app --html --serve 8081

# Scan a GitHub repository (use -- to pass flags through npm)
npm run dev scan-github -- owner/repo --html --roadmap --serve
# Or after building:
iso-sheriff scan-github owner/repo --html --roadmap --serve

ISO 27001 Controls Covered

The tool analyzes 12 high-leverage ISO 27001 controls:

1. A.8.28 - Secure Coding Standard
2. A.8.29 - Dependency Vulnerability Management
3. A.9.4.2 - Secrets Management
4. A.9.2.1 - Access Control / RBAC
5. A.12.4.1 - Logging & Monitoring
6. A.12.1.2 - Change Management
7. A.16.1.1 - Incident Response Readiness
8. A.12.3.1 - Backups & Disaster Recovery
9. A.8.1.1 - Asset Inventory
10. A.8.30 - SBOM Generation
11. A.14.1.2 - Secure Configuration
12. A.9.4.3 - Secure CI/CD

What Gets Scanned

File Presence Checks

• Security documentation (SECURITY.md, CONTRIBUTING.md)
• Configuration files (package.json, lockfiles, Dockerfile)
• CI/CD configurations (.github/workflows, .gitlab-ci.yml)
• Documentation directories (docs/security, policies, runbooks)

Pattern Matching

• Security headers (Next.js, Express)
• Authentication libraries (JWT, next-auth, passport)
• Logging libraries (pino, winston, bunyan)
• SAST tools in CI/CD
• Dependency scanning tools

Optional Tool Integrations

When --tools is enabled, the tool attempts to run:

• gitleaks: Detect secrets in code
• semgrep: Static analysis security testing
• osv-scanner: Dependency vulnerability scanning

Note: These tools must be installed separately and available in PATH.

Output Structure

.iso-sheriff/
├── report.json          # Machine-readable scan results
├── report.html          # Human-friendly HTML report
├── roadmap.md           # Prioritized action plan
└── evidence-pack/       # Starter templates
    ├── policies/
    │   └── secure-coding-standard.md
    ├── runbooks/
    │   └── incident-response.md
    ├── records/
    │   ├── asset-inventory.csv
    │   └── risk-register.csv
    └── audit/
        └── internal-audit-checklist.md

Report Contents

JSON Report

• Overall readiness score (0-100)
• Control-by-control assessment
• Findings with severity and location
• Missing evidence requirements
• Scores by category

HTML Report

• Visual dashboard with scores
• Top blockers highlighted
• Detailed control assessments
• Color-coded severity indicators

Roadmap

• 30 Days: Quick wins (CI security, headers, basic docs)
• 60 Days: Process & evidence (runbooks, risk register)
• 90 Days: Audit readiness (internal audit, management review)

Each task includes:

• Control ID and description
• Why it matters
• Required evidence
• Suggested owner (Dev/DevOps/Security/Management)

Architecture

src/
├── cli.ts              # CLI entry point
├── types.ts            # TypeScript type definitions
├── scanners/           # Repository scanners
│   ├── base.ts
│   ├── file-scanner.ts
│   ├── pattern-scanner.ts
│   └── tool-scanner.ts
├── engine/             # Control mapping engine
│   ├── analyzer.ts
│   └── mapper.ts
├── report/             # Report generators
│   ├── json-reporter.ts
│   ├── html-reporter.ts
│   └── roadmap-generator.ts
├── templates/          # Evidence pack generator
│   └── evidence-pack.ts
└── iso/                # ISO control definitions
    └── controls.json

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Development mode (with tsx)
npm run dev scan <path>

Limitations

1. Local Analysis Only: Scans only local filesystem; no cloud/remote analysis
2. Pattern-Based: Uses heuristics and patterns; may have false positives/negatives
3. Tool Dependencies: Optional tools (gitleaks, semgrep, osv-scanner) must be installed separately
4. Evidence Verification: Can only verify "AUTO" evidence; "HUMAN" evidence requires manual review
5. ISO Coverage: Covers 12 high-leverage controls; not a complete ISO 27001 audit
6. Framework Support: Optimized for Node.js/Next.js; other frameworks may have limited support

Extending

Adding New Controls

Edit src/iso/controls.json to add new controls:

{
  "controlId": "A.X.Y",
  "name": "Control Name",
  "description": "Description",
  "signals": [
    {
      "type": "file_exists",
      "value": "path/to/file",
      "description": "What to check"
    }
  ],
  "evidence": ["Required evidence"],
  "severity": "HIGH",
  "remediation": {
    "tasks": ["Task 1", "Task 2"],
    "templates": ["path/to/template.md"]
  }
}

Adding New Scanners

1. Create a new scanner class extending BaseScanner
2. Implement the scan() method
3. Add to the Analyzer class

Customizing Reports

Modify the reporter classes in src/report/ to customize output format.

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

Security

For security vulnerabilities, please see SECURITY.md for reporting instructions.

License

MIT

Disclaimer

This tool provides guidance for ISO 27001 readiness but does not guarantee compliance. Always consult with qualified security professionals and auditors for official compliance assessments.