# Story 4.15: Developer Docs for Security Scans & Artifacts

## Status: Planned

## Priority: Medium

## Estimated Effort: Small (1 day)

## Dependencies: None

## Epic / Series

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

---

## Context / Background

Developers and security operators need clear documentation for running security scans locally and finding CI artifacts. This enables them to reproduce results and approve promotions confidently.

---

## User Story

**As a** developer and security operator  
**I want** clear docs for running scans locally and finding CI artifacts  
**So that** I can reproduce results and approve promotions confidently

---

## Scope (In / Out)

### In Scope

- Update CONTRIBUTING.md with scan commands and prerequisites
- Update docs/security-operator-workflows.md with artifact paths and gating policy
- Add README badges/links to code scanning and artifacts page

### Out of Scope

- Implementing the actual security scanning (covered in Story 4.13)
- Creating new security tools
- Modifying CI workflows (covered in Story 4.13)

---

## Acceptance Criteria

### AC1: CONTRIBUTING.md Updates

- [ ] CONTRIBUTING.md includes commands for:
  - [ ] bandit SAST scanning
  - [ ] pip-audit vulnerability scanning
  - [ ] CycloneDX SBOM generation
- [ ] Prerequisites and setup instructions are clear
- [ ] Examples show expected output

### AC2: Security Operator Workflows Documentation

- [ ] docs/security-operator-workflows.md updated with:
  - [ ] Artifact locations (where to find scan results)
  - [ ] Approval flow documentation
  - [ ] Gating policy explanation

### AC3: README Integration

- [ ] README includes short section linking to:
  - [ ] Security artifacts
  - [ ] Code scanning UI
- [ ] Badges or links are prominently displayed

---

## Technical Design / Implementation Notes

### Documentation Locations

- Primary: `CONTRIBUTING.md` - Developer-facing scan commands
- Secondary: `docs/security-operator-workflows.md` - Operator workflows
- Integration: `README.md` - Quick links and badges

### Content Structure

1. **CONTRIBUTING.md additions:**
   ```markdown
   ## Security Scanning
   
   ### Running Scans Locally
   
   #### Bandit (SAST)
   ```bash
   bandit -r src/
   ```
   
   #### pip-audit (Vulnerability Scanning)
   ```bash
   pip-audit
   ```
   
   #### SBOM Generation
   ```bash
   cyclonedx-bom -o sbom.json
   ```
   ```

2. **Security workflows doc:**
   - Artifact paths: `security-artifacts/` on gh-pages
   - Approval process flow
   - Gating criteria

3. **README badges:**
   - Link to GitHub Security tab
   - Link to security artifacts page

---

## Tasks

- [ ] Update CONTRIBUTING.md with scan commands
- [ ] Update docs/security-operator-workflows.md with artifact locations
- [ ] Add README section with security links
- [ ] Review and test all commands locally
- [ ] Verify links work correctly

---

## Tests

### Manual Verification

- [ ] All commands in CONTRIBUTING.md work when run locally
- [ ] Links in README are accessible
- [ ] Documentation is clear and actionable

---

## Documentation Updates

- [ ] CONTRIBUTING.md - Add security scanning section
- [ ] docs/security-operator-workflows.md - Update with artifact info
- [ ] README.md - Add security section with links

---

## 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:** Documentation becomes outdated
  - **Mitigation:** Regular reviews, link validation in CI

- **Risk:** Commands don't work in all environments
  - **Mitigation:** Test on multiple platforms, provide alternatives

### Rollback Plan

- Documentation changes can be reverted via git
- No code changes, so no rollback needed

### Success Metrics / Monitoring

- Documentation clarity feedback from developers
- Reduction in questions about security scanning
- Usage of documented commands

---

## Related Documents

- [Story 4.13: CI Security Scanning & SBOM Publishing](./4.13.ci-security-scanning-sbom.md)
- [Security Operator Workflows](../security-operator-workflows.md)

---

## Change Log

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