asf-tooling opened a new issue, #1049:
URL: https://github.com/apache/tooling-trusted-releases/issues/1049
**ASVS Level(s):** L1
**Description:**
### Summary
The authorization documentation (`atr/docs/authorization-security.md`)
comprehensively covers releases, tokens, and check ignores, but lacks
documented authorization rules for Distribution Management, SSH/Rsync Access
Control, Key Management, Policy Management, Project Management, and Admin
Operations. These operations have authorization controls implemented via the
storage layer and explicit checks, but without documentation, they cannot be
systematically verified during security audits or developer onboarding.
### Details
The missing documentation areas include:
- Distribution Management (automate, record, delete operations)
- SSH/Rsync Access Control (read/write phase restrictions, path validation)
- Key Management (OpenPGP and SSH key operations, committee associations)
- Policy Management (compose/vote/finish settings, workflow configuration)
- Project Management (create, delete, lifecycle operations)
- Admin Operations (beyond token revocation)
Without comprehensive documentation, security reviewers cannot verify
complete authorization coverage, and developers may inadvertently introduce
authorization gaps.
### Recommended Remediation
Add comprehensive sections to `atr/docs/authorization-security.md`:
1. **Distribution Management Authorization**
- Document automate, record, delete operations
- Specify committee member requirements
- Document phase-based restrictions
2. **SSH/Rsync Access Authorization**
- Create phase-based access control matrix
- Document path validation rules
- Specify read/write restrictions by phase
3. **Key Management Authorization**
- Document OpenPGP operations (add, remove, associate)
- Document SSH key operations
- Specify ownership and committee participation requirements
4. **Policy Management Authorization**
- Document compose/vote/finish policy updates
- Specify PMC member requirements
5. **Project Management Authorization**
- Document create/delete/update operations
- Specify authorization requirements
6. **Admin Operations Authorization**
- Complete list of admin-only operations
- Document admin impersonation controls
Add operation-level authorization matrix to each storage writer module
docstring. Create `atr/docs/authorization-matrix.md` with comprehensive
endpoint mapping.
### Acceptance Criteria
- [ ] Distribution Management section added to authorization-security.md
- [ ] SSH/Rsync Access section added with phase-based matrix
- [ ] Key Management section added with operation details
- [ ] Policy Management section added
- [ ] Project Management section added
- [ ] Admin Operations section added with complete operation list
- [ ] authorization-matrix.md created with endpoint mapping
- [ ] Storage writer module docstrings updated with authorization details
- [ ] Developer guide updated with authorization examples
### References
- Source reports: L1:8.1.1.md
- Related findings: FINDING-158, FINDING-159, FINDING-160
- ASVS sections: 8.1.1
### Priority
Medium
---
---
### Consolidated: FINDING-158 - Phase-Based Authorization Rules Not
Consolidated
**ASVS Level(s):** L1
**Description:**
### Summary
Release lifecycle phases govern which operations are permitted, but these
phase-based authorization rules are scattered across multiple files
(`atr/get/download.py`, `atr/ssh.py`, `atr/storage/writers/release.py`,
`atr/get/vote.py`) with no consolidated reference. A developer or auditor must
trace through multiple code paths to understand the complete phase access
matrix. This makes it difficult to verify complete phase authorization
coverage, ensure consistent enforcement, and maintain the authorization model.
### Details
Phase-based rules are implemented in:
- `atr/get/download.py` - download restrictions by phase
- `atr/ssh.py` - SSH access restrictions by phase
- `atr/storage/writers/release.py` - phase transition logic
- `atr/get/vote.py` - voting restrictions by phase
- `atr/post/upload.py` - upload restrictions by phase
Without consolidated documentation, it's unclear whether all operations
correctly enforce phase restrictions, and future modifications may introduce
inconsistencies.
### Recommended Remediation
Add consolidated phase access matrix to `atr/docs/authorization-security.md`:
```markdown
## Phase-Based Access Control
### Phase Definitions
| Phase | Description | Purpose |
|-------|-------------|---------|
| RELEASE_CANDIDATE_DRAFT | Initial creation | Artifact upload and editing |
| RELEASE_CANDIDATE | Voting phase | Community review and voting |
| RELEASE_PREVIEW | Post-vote preview | Final verification before release |
| RELEASE | Published release | Public distribution |
### Operation Access by Phase Matrix
| Operation | DRAFT | CANDIDATE | PREVIEW | RELEASE | Authorization |
|-----------|-------|-----------|---------|---------|---------------|
| Upload artifacts | ✓ | ✗ | ✗ | ✗ | Project participants |
| SSH write access | ✓ | ✗ | ✗ | ✗ | Project participants |
| SSH read access | ✓ | ✓ | ✓ | ✗ | Project participants |
| Start vote | ✓ | ✗ | ✗ | ✗ | PMC members |
| Cast vote | ✗ | ✓ | ✗ | ✗ | PMC members |
| Resolve vote | ✗ | ✓ | ✗ | ✗ | PMC members |
| Promote to preview | ✗ | ✓ | ✗ | ✗ | PMC members (after vote) |
| Announce release | ✗ | ✗ | ✓ | ✗ | PMC members |
| Download artifacts | ✓ | ✓ | ✓ | ✓ | Public (phase-dependent) |
### Phase Transition Requirements
| Transition | Required Conditions | Authorization |
|------------|---------------------|---------------|
| DRAFT → CANDIDATE | No blocker checks, has files, no ongoing tasks |
Project participants |
| CANDIDATE → PREVIEW | Vote resolved successfully, distribution automated |
PMC members |
| PREVIEW → RELEASE | Announcement sent | PMC members |
| Any → DRAFT | Cancellation | PMC members or admins |
### Enforcement Locations
- SSH access: `atr/ssh.py` lines 283-323
- Phase transitions: `atr/storage/writers/release.py` lines 180-220
- Vote operations: `atr/storage/writers/vote.py` lines 45-60
- Announcements: `atr/storage/writers/announce.py` lines 83-84
```
Add phase validation helper function to reduce code duplication. Add phase
transition audit logging. Create phase transition diagram in documentation.
### Acceptance Criteria
- [ ] Phase access matrix added to authorization-security.md
- [ ] Phase definitions table documented
- [ ] Operation access by phase matrix created
- [ ] Phase transition requirements documented
- [ ] Enforcement locations documented with code references
- [ ] Phase validation helper function created
- [ ] Phase transition audit logging added
- [ ] Phase transition diagram created
- [ ] Phase-based integration tests added for all operations
### References
- Source reports: L1:8.1.1.md
- Related findings: FINDING-157, FINDING-160
- ASVS sections: 8.1.1
### Priority
Medium
---
---
### Consolidated: FINDING-159 - Authorization Documentation Lacks
Field-Level Write Access Restrictions
**ASVS Level(s):** L2-only
**Description:**
### Summary
Authorization documentation defines operation-level access (who can start
releases, resolve votes, etc.) but does not specify which fields of each entity
each role can write, or how field access changes based on resource state. ASVS
8.1.2 explicitly requires documentation of "field-level access restrictions
(both read and write) based on consumer permissions and resource attributes."
Undocumented field-level rules exist in code including: `Release.phase` (only
via state transitions), `Release.vote_resolved` (PMC members only,
RELEASE_CANDIDATE phase only), `ReleasePolicy.manual_vote` (PMC members;
disallowed for podlings), `ReleasePolicy.min_hours` (PMC members; must be 0 or
72-144), and others.
### Details
The issue spans `atr/docs/authorization-security.md`,
`atr/docs/storage-interface.md`, and storage writer modules. While field-level
restrictions are implemented in code (e.g., `atr/storage/writers/release.py`,
`atr/storage/writers/policy.py`, `atr/storage/writers/checks.py` lines 87-130),
they are not documented in a systematic, auditable format.
### Recommended Remediation
Add field-level access matrix to `authorization-security.md`:
```markdown
## Field-Level Write Access Restrictions
### Release Entity
| Field | Writable By | Conditions | Constraints |
|-------|-------------|------------|-------------|
| phase | Project participants, PMC members | Via state transitions only |
Must follow transition rules |
| vote_resolved | PMC members | RELEASE_CANDIDATE phase only | Boolean value
|
| vote_started | PMC members | DRAFT phase, ready for vote | Timestamp |
| artifacts | Project participants | DRAFT phase only | File uploads |
### ReleasePolicy Entity
| Field | Writable By | Conditions | Constraints |
|-------|-------------|------------|-------------|
| manual_vote | PMC members | Not for podlings | Boolean |
| min_hours | PMC members | - | 0 or 72-144 |
| github_repository_name | PMC members | Valid repository format | String
pattern |
| github_workflow_path | PMC members | Valid path format | String pattern |
### CheckResultIgnore Entity
| Field | Writable By | Conditions | Constraints |
|-------|-------------|------------|-------------|
| pattern | PMC members | Valid regex | Regex pattern |
| reason | PMC members | - | Non-empty string |
| asf_uid | System | Ownership transfer on delete | Immutable after creation
|
### PublicSigningKey Entity
| Field | Writable By | Conditions | Constraints |
|-------|-------------|------------|-------------|
| key_data | Committee participants | Valid key format | PGP key block |
| committee_id | Committee participants | Member of target committee |
Foreign key |
```
Include verification steps: create field-level access matrix document,
review all storage writer methods to extract field rules, document ownership
transfer behaviors, document immutable fields, cross-reference with
operation-level documentation, add to security review checklist.
### Acceptance Criteria
- [ ] Field-level access matrix added for Release entity
- [ ] Field-level access matrix added for ReleasePolicy entity
- [ ] Field-level access matrix added for CheckResultIgnore entity
- [ ] Field-level access matrix added for PublicSigningKey entity
- [ ] Ownership transfer behaviors documented
- [ ] Immutable fields documented
- [ ] Cross-references added to operation-level documentation
- [ ] Security review checklist updated with field-level review items
### References
- Source reports: L2:8.1.2.md
- Related findings: FINDING-157, FINDING-160
- ASVS sections: 8.1.2
### Priority
Medium
---
---
### Consolidated: FINDING-160 - State-Dependent Access Rules Not
Systematically Documented
**ASVS Level(s):** L2-only
**Description:**
### Summary
The Release entity has four phases (RELEASE_CANDIDATE_DRAFT,
RELEASE_CANDIDATE, RELEASE_PREVIEW, RELEASE) that fundamentally change
permitted operations and field modifications. ASVS 8.1.2 explicitly requires
documentation of rules that "depend on other attribute values of the relevant
data object, such as state or status." While some phase-dependent rules are
documented at operation level, systematic field-level state-dependent rules are
not documented. Undocumented state-dependent rules include phase transition
requirements, SSH access by phase, distribution requirements for transitions,
and vote resolution restrictions.
### Details
State-dependent rules are scattered across:
- `atr/storage/writers/announce.py` lines 83-84 (announcement phase
requirements)
- `atr/ssh.py` lines 283-323 (SSH access by phase)
- `atr/storage/writers/release.py` lines 180-220 (phase transitions)
- `atr/storage/writers/vote.py` lines 45-60 (vote resolution phase)
Without systematic documentation, developers cannot easily understand the
complete state machine and may introduce bugs or security gaps.
### Recommended Remediation
Add state machine documentation to `authorization-security.md`:
```markdown
## State-Dependent Access Rules
### State Transitions
| Current Phase | Allowed Transition | Required Role | Additional Conditions
|
|--------------|-------------------|---------------|----------------------|
| DRAFT | → CANDIDATE | Project participants | No blocker checks, has files,
no ongoing tasks |
| CANDIDATE | → PREVIEW | PMC members | Vote resolved successfully,
distribution automated |
| PREVIEW | → RELEASE | PMC members | Announcement sent to mailing lists |
| Any | → DRAFT | PMC members/admins | Cancellation or rollback |
### Field Access by Phase
| Field | DRAFT | CANDIDATE | PREVIEW | RELEASE | Notes |
|-------|-------|-----------|---------|---------|-------|
| artifacts (write) | ✓ | ✗ | ✗ | ✗ | Upload only in DRAFT |
| vote_resolved (write) | ✗ | ✓ | ✗ | ✗ | PMC members only |
| announcement_sent | ✗ | ✗ | ✓ | ✗ | System-managed |
### Operation Availability by Phase
| Operation | DRAFT | CANDIDATE | PREVIEW | RELEASE | Authorization |
|-----------|-------|-----------|---------|---------|---------------|
| Upload artifacts | ✓ | ✗ | ✗ | ✗ | Project participants |
| Start vote | ✓ | ✗ | ✗ | ✗ | PMC members |
| Cast vote | ✗ | ✓ | ✗ | ✗ | PMC members |
| Resolve vote | ✗ | ✓ | ✗ | ✗ | PMC members |
| Send announcement | ✗ | ✗ | ✓ | ✗ | PMC members |
### SSH/Rsync Access by Phase
| Phase | Read Access | Write Access | Rationale |
|-------|-------------|--------------|-----------|
| DRAFT | ✓ | ✓ | Active development |
| CANDIDATE | ✓ | ✗ | Voting requires immutable artifacts |
| PREVIEW | ✓ | ✗ | Final verification before release |
| RELEASE | ✗ | ✗ | Use distribution channels |
### Distribution State Requirements
- **PREVIEW → RELEASE transition:** Requires announcement sent to
appropriate mailing lists
- **Distribution automation:** Must complete before CANDIDATE → PREVIEW
transition
```
Add verification steps: create state machine diagram, document preconditions
for each transition, create field access matrix by phase, document operation
availability by phase, add state machine tests, include in developer onboarding.
### Acceptance Criteria
- [ ] State transition table added to documentation
- [ ] Field access by phase matrix created
- [ ] Operation availability by phase documented
- [ ] SSH/Rsync access by phase documented with rationale
- [ ] Distribution state requirements documented
- [ ] State machine diagram created
- [ ] State machine tests added to verify documented behavior
- [ ] Documentation included in developer onboarding materials
### References
- Source reports: L2:8.1.2.md
- Related findings: FINDING-157, FINDING-158, FINDING-159
- ASVS sections: 8.1.2
### Priority
Medium
---
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
