# Story 4.13: CI Security Scanning & SBOM Publishing

## Status: Planned

## Priority: High

## Estimated Effort: Medium (2-3 days)

## Dependencies: None

## Epic / Series

Part of Epic 4: Enterprise Compliance & Observability / Series 4.x

---

## Context / Background

Security-focused maintainers need automated security scans (bandit, pip-audit) and SBOM generation in CI with published artifacts. This enables supply-chain and vulnerability compliance enforcement without burdening developers.

---

## User Story

**As a** security-focused maintainer  
**I want** automated security scans (bandit, pip-audit) and SBOM generation in CI with published artifacts  
**So that** we can enforce supply-chain and vulnerability compliance without burdening developers

---

## Scope (In / Out)

### In Scope

- GitHub Actions workflows for:
  - bandit SAST scanning (upload SARIF to GitHub code scanning)
  - pip-audit vulnerability scanning (produce JSON artifact)
  - CycloneDX SBOM generation (produce sbom.json artifact)
- Artifact publishing to gh-pages under security-artifacts/
- Release workflow gates (fail on critical vulns, warn-only on PRs)
- Documentation updates

### Out of Scope

- Fixing vulnerabilities (separate work)
- Real-time scanning
- Custom security tools

---

## Acceptance Criteria

### AC1: CI Workflows

- [ ] GitHub Actions workflow runs on PR and main for:
  - [ ] bandit SAST scan
  - [ ] Upload SARIF to GitHub code scanning
  - [ ] pip-audit vulnerability scan
  - [ ] Produce JSON artifact from pip-audit
  - [ ] CycloneDX SBOM generation (pip)
  - [ ] Produce sbom.json artifact

### AC2: Artifact Publishing

- [ ] Artifacts uploaded on each CI run
- [ ] On main branch, publish to gh-pages under `security-artifacts/`
- [ ] Artifacts are versioned or timestamped
- [ ] Artifacts are accessible via web

### AC3: Release Workflow Gates

- [ ] Release workflow fails on critical vulnerabilities
- [ ] PRs allow warn-only (don't block)
- [ ] Configurable severity thresholds
- [ ] Clear error messages

### AC4: Documentation

- [ ] Brief README section linking to security artifacts
- [ ] CONTRIBUTING.md includes scan commands (see Story 4.15)
- [ ] Workflow documentation updated

---

## Technical Design / Implementation Notes

### Workflow Structure

Location: `.github/workflows/security-scanning.yml`

```yaml
name: Security Scanning

on:
  pull_request:
  push:
    branches: [main]

jobs:
  bandit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run Bandit
        run: bandit -r src/ -f json -o bandit-report.json
      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v2
        with:
          sarif_file: bandit-report.json
  
  pip-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run pip-audit
        run: pip-audit --format json --output pip-audit.json
      - name: Upload artifact
        uses: actions/upload-artifact@v3
        with:
          name: pip-audit
          path: pip-audit.json
  
  sbom:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Generate SBOM
        run: cyclonedx-bom -o sbom.json
      - name: Upload artifact
        uses: actions/upload-artifact@v3
        with:
          name: sbom
          path: sbom.json
  
  publish:
    if: github.ref == 'refs/heads/main'
    needs: [bandit, pip-audit, sbom]
    runs-on: ubuntu-latest
    steps:
      - name: Publish to gh-pages
        # Publish artifacts to security-artifacts/ directory
```

### Artifact Format

- **pip-audit.json**: Standard pip-audit JSON format
- **sbom.json**: CycloneDX format
- **bandit-report.json**: SARIF format

### Publishing Strategy

- Publish to `gh-pages` branch under `security-artifacts/`
- Use versioned paths: `security-artifacts/v{version}/` or timestamped
- Make artifacts accessible via GitHub Pages

---

## Tasks

### Phase 1: Workflow Setup
- [ ] Create `.github/workflows/security-scanning.yml`
- [ ] Configure bandit scanning
- [ ] Configure pip-audit scanning
- [ ] Configure SBOM generation
- [ ] Test workflows locally

### Phase 2: Artifact Publishing
- [ ] Set up gh-pages publishing
- [ ] Configure artifact paths
- [ ] Test publishing workflow

### Phase 3: Release Gates
- [ ] Add vulnerability checks to release workflow
- [ ] Configure severity thresholds
- [ ] Test gate behavior

### Phase 4: Documentation
- [ ] Update README with security section
- [ ] Document artifact locations
- [ ] Document workflow behavior

---

## Tests

### Manual Verification

- [ ] Workflows run successfully on PR
- [ ] Workflows run successfully on main
- [ ] Artifacts are generated correctly
- [ ] Artifacts are published to gh-pages
- [ ] Release gates work as expected

---

## Documentation Updates

- [ ] README.md - Add security scanning section
- [ ] CONTRIBUTING.md - Add scan commands (Story 4.15)
- [ ] Workflow documentation

---

## Definition of Done

Story is complete when ALL of the following are true:

### Code Complete
- [ ] All acceptance criteria met and verified
- [ ] All tasks completed
- [ ] Code follows project style guide
- [ ] No linting errors or warnings
- [ ] Type checking passes (mypy strict)

### Quality Assurance
- [ ] Unit tests: >90% coverage of new code
- [ ] Integration tests: all scenarios passing
- [ ] Regression tests: no existing functionality broken
- [ ] Performance tests: no regression vs baseline
- [ ] Manual testing completed (if applicable)

### Documentation
- [ ] User-facing docs updated
- [ ] API reference updated (if applicable)
- [ ] Code examples added/updated
- [ ] CHANGELOG.md updated
- [ ] Inline code documentation complete

### Review & Release
- [ ] Code review approved
- [ ] Documentation reviewed for clarity
- [ ] CI/CD pipeline passing
- [ ] Ready for merge to main branch

### Backwards Compatibility
- [ ] No breaking changes OR breaking changes documented with migration guide
- [ ] Existing tests still pass
- [ ] Deprecation warnings added (if applicable)

---

## Risks / Rollback / Monitoring

### Risks

- **Risk:** High false positive rate from scanners
  - **Mitigation:** Tune scanner configurations, allowlist known false positives

- **Risk:** Publishing workflow breaks gh-pages
  - **Mitigation:** Test thoroughly, use separate workflow

### Rollback Plan

- Disable workflows if needed
- Remove publishing step
- Keep artifacts in GitHub Actions only

---

## Related Documents

- [Story 4.14: Marketplace Security Signals](./4.14.marketplace-security-signals.md)
- [Story 4.15: Developer Docs for Security Scans](./4.15.developer-docs-security-scans.md)

---

## Change Log

| Date       | Change                    | Author |
| ---------- | ------------------------- | ------ |
| 2025-01-10 | Initial story creation    | System |
