Security Documentation

README.md

@@ -1,5 +1,7 @@
 # Specifications
 
+## Protocol Specifications
+
   * [Endpoints](./endpoints.md)
   * [HTTP API](./http_api.md)
   * [ETS registry format](./registry-v1.md) (Deprecated)
@@ -10,6 +12,10 @@
 
   * [purl (Package URL) format](./package-url.md)
 
+## Security
+
+  * [Security Documentation](./security/README.md) - Threat model, SDLC, operations, supply chain, compliance
+
 ## Repositories and mirrors
 
 To host a repository only the [Repository endpoint](./endpoints.md#repository) has to be implemented.

security/README.md

@@ -0,0 +1,58 @@
+# Security Documentation
+
+This documentation describes the security model, practices, and controls for the Hex package ecosystem.
+
+## Overview
+
+Hex.pm is a package registry for the Erlang and Elixir ecosystem. It enables publishing, discovery, and consumption of packages used in production systems. This documentation covers:
+
+- What we protect and what can go wrong (threat model)
+- How we build and release software securely (SDLC)
+- How we operate and respond to incidents (operations)
+- How we ensure package integrity (supply chain)
+
+## Documentation Structure
+
+### [Threat Model](./threat-model/overview.md)
+
+Analysis of assets, actors, threats, and mitigations.
+
+- [Overview](./threat-model/overview.md) - Scope and methodology
+- [Architecture](./threat-model/architecture.md) - System overview and trust boundaries
+- [Assets](./threat-model/assets.md) - What we protect
+- [Actors](./threat-model/actors.md) - Legitimate users and adversaries
+- [Threats](./threat-model/threats.md) - Key threats to the ecosystem
+- [Mitigations](./threat-model/mitigations.md) - How threats are addressed
+- [Assumptions](./threat-model/assumptions.md) - What we assume and don't guarantee
+
+### [Secure Development Lifecycle](./sdlc/README.md)
+
+How we build and maintain secure software, organized into three pillars.
+
+- [Overview](./sdlc/README.md) - SDLC structure and registers
+- [Secure Build](./sdlc/build.md) - Artifact provenance, dependencies, toolchain
+- [Secure Process](./sdlc/process.md) - Code review, QA, security scanning, vulnerability handling
+- [Secure Runtime](./sdlc/runtime.md) - Deployment, secrets, monitoring
+- [Risk Register](./sdlc/risk-register.md) - Accepted risks and mitigations
+- [Exception Register](./sdlc/exception-register.md) - Approved policy deviations
+
+### [Operations](./operations/incident-response.md)
+
+How we operate and respond to security events.
+
+- [Incident Response](./operations/incident-response.md) - Triage, response, notification
+- [Access Control](./operations/access-control.md) - Internal access principles
+
+### [Supply Chain Security](./supply-chain/overview.md)
+
+How we ensure package integrity from publish to install.
+
+- [Overview](./supply-chain/overview.md) - Supply chain security approach
+- [Provenance](./supply-chain/provenance.md) - Build origin and attestations
+- [Signing](./supply-chain/signing.md) - Registry signing and checksums
+- [Verification](./supply-chain/verification.md) - Client-side verification
+
+## Related Documentation
+
+- [Client Flows](./threat-model/client-flows.md) - Authentication and verification flows
+- [Endpoints](../endpoints.md) - API and repository endpoints

security/operations/access-control.md

@@ -0,0 +1,54 @@
+# Access Control
+
+This document describes access control for Hex infrastructure.
+
+## Application Access Levels
+
+### Public Access
+
+- Package downloads (public packages)
+- Registry metadata
+- Documentation viewing
+
+### Authenticated User Access
+
+- Publishing packages (own packages)
+- Managing account settings
+- Viewing private packages (with permission)
+
+### Organization Admin Access
+
+- Managing organization members
+- Configuring private repositories
+- Billing management
+
+### Operator Access
+
+- Infrastructure administration
+- Incident response
+- Policy enforcement
+
+## Infrastructure Access
+
+### Production Systems
+
+A small number of operators have access to production infrastructure.
+Access is logged via GCP Cloud Logging and GKE audit logs.
+
+### Cloud Provider Access
+
+- CI/CD uses OIDC workload identity federation (no long-lived service account keys)
+- Kubernetes access controlled via RBAC
+- Infrastructure changes applied via CI pipeline
+
+### Database Access
+
+- Direct production database access restricted to operators
+- Application accesses database via dedicated service credentials
+
+## Audit
+
+### Logging
+
+- GKE and infrastructure events logged to GCP Cloud Logging
+- Application-level audit log for security-relevant actions (publish, ownership changes, etc.)

security/operations/incident-response.md

@@ -0,0 +1,96 @@
+# Incident Response
+
+This document describes incident response procedures for the Hex ecosystem.
+
+## Incident Classification
+
+### Severity Levels
+
+| Level | Description | Examples |
+|-------|-------------|----------|
+| Critical | Active exploitation, widespread impact | Registry compromise, malicious package spreading |
+| High | Significant risk, limited exploitation | Account takeovers, targeted attacks |
+| Medium | Potential risk, no active exploitation | Vulnerability discovered, suspicious activity |
+| Low | Minor issues, minimal impact | Policy violations, minor misconfigurations |
+
+## Response Procedures
+
+### Detection
+
+- Monitoring alerts
+- User reports
+- Security researcher reports
+- Automated scanning
+
+### Triage
+
+1. Assess severity and scope
+2. Identify affected systems/users
+3. Determine response urgency
+4. Assign incident owner
+
+### Containment
+
+- Revoke compromised credentials
+- Disable affected accounts (if necessary)
+- Block malicious packages
+- Isolate affected systems
+
+### Eradication
+
+- Remove malicious content
+- Patch vulnerabilities
+- Reset compromised credentials
+- Verify no persistence mechanisms
+
+### Recovery
+
+- Restore normal operations
+- Monitor for recurrence
+- Communicate with affected users
+
+### Post-Incident
+
+- Document incident timeline
+- Identify root cause
+- Implement preventive measures
+- Update procedures as needed
+
+## Communication
+
+### Internal
+
+- Incident channel for coordination
+- Regular status updates
+- Clear ownership and escalation
+
+### External
+
+- User notification when affected
+- Public disclosure when appropriate
+- Coordinate with reporters
+
+## Specific Scenarios
+
+### Compromised Maintainer Account
+
+1. Disable account access
+2. Revoke all tokens
+3. Review recent publishing activity
+4. Contact maintainer via verified channel
+5. Consider retiring suspicious versions
+
+### Malicious Package
+
+1. Mark package/version as retired
+2. Notify users who downloaded recently
+3. Investigate publishing account
+4. Document for community awareness
+
+### Infrastructure Compromise
+
+1. Isolate affected systems
+2. Assess scope of access
+3. Rotate all credentials
+4. Rebuild from known-good state
+5. Full security audit

security/sdlc/README.md

@@ -0,0 +1,47 @@
+# Secure Development Lifecycle
+
+This documentation describes the secure development practices for Hex registry
+infrastructure, organized into three pillars.
+
+## Pillars
+
+### [Secure Build](./build.md)
+
+How we build software securely:
+
+- Artifact provenance and integrity
+- Dependency management and constraints
+- Toolchain security (CI/CD, compilers, formatters)
+
+### [Secure Process](./process.md)
+
+How we develop software securely:
+
+- Code review requirements
+- Quality assurance and testing
+- Security scanning
+- Vulnerability handling and disclosure
+
+### [Secure Runtime](./runtime.md)
+
+How we run software securely:
+
+- Deployment controls
+- Secrets management
+- Service ownership
+- Monitoring and observability
+
+## Registers
+
+### [Risk Register](./risk-register.md)
+
+Tracked security risks with their severity, status, and mitigations.
+
+### [Exception Register](./exception-register.md)
+
+Approved deviations from security policies with justification and expiry.
+
+## Related Documentation
+
+- [Supply Chain Security](../supply-chain/overview.md) - Package integrity from publish to install
+- [Operations](../operations/incident-response.md) - Incident response and access control

security/sdlc/build.md

@@ -0,0 +1,101 @@
+# Secure Build
+
+This document describes secure build practices for Hex registry infrastructure.
+
+## Artifact Provenance
+
+### Docker Images
+
+| Property | Implementation |
+|----------|----------------|
+| Image digest | SHA256 of image manifest |
+| Push by digest | Ensures immutability |
+| Multi-platform manifests | Consistent across architectures |
+| Git commit linking | Image tagged with short SHA |
+
+### Image Tagging
+
+| Tag Format | Example | Purpose |
+|------------|---------|---------|
+| Short SHA | `abc1234` | Identifies specific commit |
+| Registry | `gcr.io/hexpm-prod/hexpm` | GCP Container Registry |
+
+### Package Releases
+
+| Property | Implementation |
+|----------|----------------|
+| Checksums | SHA-256 in signed registry |
+| Immutability | Cannot modify after grace period |
+| Registry signing | RSA-SHA512 signatures |
+
+## Dependencies
+
+### Automated Updates
+
+Most Hex projects use GitHub Dependabot for automated dependency updates:
+
+| Repository | Dependabot | Ecosystems |
+|------------|------------|------------|
+| hexpm/hexpm | Yes | github-actions, mix |
+| hexpm/hex | Yes | github-actions, mix |
+| hexpm/hex_core | Yes | github-actions, rebar |
+| hexpm/hex_solver | Yes | github-actions, mix |
+| hexpm/hexdocs | Yes | github-actions, mix |
+| hexpm/preview | Yes | github-actions, mix |
+| hexpm/diff | Yes | github-actions, mix |
+| hexpm/specifications | Yes | github-actions |
+| hexpm/bob | No | - |
+| hexpm/hexdocs-search | No | - |
+
+### Dependency Constraints
+
+Some projects have restrictions on external dependencies:
+
+| Project | Constraint | Reason |
+|---------|------------|--------|
+| hex | No external deps | Bootstrapped before package manager available |
+| hex_core | No external deps | Designed to be vendored by clients |
+
+These projects must only use OTP standard library functions or vendor library code.
+
+### Dependency Selection
+
+| Criterion | Consideration |
+|-----------|---------------|
+| Maintenance status | Active development and releases |
+| Security track record | History of vulnerabilities and response |
+| Community adoption | Usage and community support |
+| License compatibility | Apache 2.0 / MIT preferred |
+
+### Minimization Principles
+
+| Principle | Implementation |
+|-----------|----------------|
+| Prefer standard library | Use OTP/Elixir stdlib when sufficient |
+| Avoid unnecessary deps | Each dependency adds attack surface |
+| Evaluate transitives | Consider full dependency tree |
+
+## Toolchain
+
+### CI Pipeline
+
+| Check | Description |
+|-------|-------------|
+| Formatting | Code formatting enforced in CI |
+| Unit tests | Automated tests run on every PR |
+| CodeQL | Security scanning for GitHub Actions workflows |
+| Zizmor | GitHub Actions security best practices |
+
+### Authentication (CI)
+
+| Stage | Method |
+|-------|--------|
+| GCP authentication | Workload Identity Federation (OIDC) |
+| Container Registry | OAuth2 access token |
+| No long-lived secrets | Short-lived tokens from OIDC |
+
+## Related Documentation
+
+- [Secure Process](./process.md) - Code review and quality assurance
+- [Secure Runtime](./runtime.md) - Deployment and operations
+- [Supply Chain - Signing](../supply-chain/signing.md) - Registry signing