asf-tooling opened a new issue, #1104:
URL: https://github.com/apache/tooling-trusted-releases/issues/1104
**ASVS Level(s):** L2-only
**Description:**
### Summary
The `input-validation.md` documentation defines data integrity validation
rules in `validate.py`, but does not document significant cross-entity
contextual validation rules implemented in `atr/db/interaction.py` and other
modules. ASVS 2.1.2 explicitly requires documentation to define how logical and
contextual consistency is validated. Undocumented rules include vote readiness
cross-checks, trusted publishing phase matching, email recipient domain
validation, and repository/workflow validation.
### Details
The issue exists in `atr/docs/input-validation.md` (missing documentation)
and implementation in `atr/db/interaction.py` lines 220-260, 310-340, 410-440,
and `atr/mail.py` lines 115-125.
### Recommended Remediation
Add a 'Business Logic Validation' section to `input-validation.md`:
```markdown
## Business Logic Validation
### Cross-Entity Contextual Validation
Beyond field-level validation, ATR enforces business rules that span
multiple entities and depend on system state.
#### Vote Initiation Requirements
**Function:** `release_ready_for_vote()` in `atr/db/interaction.py`
**Rules:**
- Release must be in RELEASE_CANDIDATE_DRAFT phase
- No blocker-severity check failures
- At least one artifact file present
- No ongoing background tasks
- Vote thread must not already exist
**Enforcement:** Called before starting vote via `/vote/start` endpoint
#### Trusted Publishing Validation
**Function:** `trusted_jwt_for_dist()` and `_trusted_project()` in
`atr/db/interaction.py`
**Rules:**
- GitHub JWT subject must match configured repository
- Workflow path must match configured path
- Release must be in RELEASE_PREVIEW phase
- Distribution record must exist for the release
**Enforcement:** Called during GitHub Actions trusted publishing workflow
#### Email Recipient Domain Validation
**Function:** `_validate_recipient()` in `atr/mail.py`
**Rules:**
- Recipient email must end with `@apache.org` or configured allowed domains
- Prevents email to arbitrary external addresses
- Applied to announcement and vote emails
**Enforcement:** Called before sending any email
#### Repository/Workflow Validation
**Function:** Policy validation in `atr/storage/writers/policy.py`
**Rules:**
- GitHub repository name must match pattern: `apache/{project_name}`
- Workflow path must be within `.github/workflows/`
- Workflow file must exist in repository
**Enforcement:** Applied when updating release policy configuration
### Contextual Consistency Examples
| Validation Rule | Entities Involved | Enforcement Location |
|----------------|-------------------|---------------------|
| Vote readiness | Release, CheckResult, WorkflowStatus |
`release_ready_for_vote()` |
| Trusted publishing | Release, Distribution, GitHub JWT |
`trusted_jwt_for_dist()` |
| Email recipients | EmailMessage, Configuration | `_validate_recipient()` |
| Phase transitions | Release, WorkflowStatus, CheckResult |
`atr/storage/writers/release.py` |
| Distribution automation | Release, Distribution, Policy |
`atr/storage/writers/announce.py` |
### Additional Business Rules
- **Rate Limiting:** API endpoints enforce per-user rate limits (documented
in `atr/blueprints/api.py`)
- **Archive Extraction:** Maximum file count, size, and depth limits
(documented in `atr/tasks/checks/`)
- **Voting Business Rules:** Quorum requirements, vote resolution logic
(documented in `atr/shared/vote.py`)
- **Session Lifecycle:** Inactivity timeout (7 days), absolute maximum (72
hours) (documented in `src/asfquart/session.py`)
- **Trusted Publishing:** JWT validation, phase matching (documented in
`atr/db/interaction.py`)
- **Distribution Retry Logic:** Exponential backoff, maximum attempts
(documented in `atr/tasks/distribution.py`)
```
### Acceptance Criteria
- [ ] Business Logic Validation section added to input-validation.md
- [ ] Vote initiation requirements documented
- [ ] Trusted publishing validation rules documented
- [ ] Email recipient domain validation documented
- [ ] Repository/workflow validation documented
- [ ] Contextual consistency table created
- [ ] Additional business rules documented
- [ ] Cross-references added to implementation files
- [ ] Documentation reviewed and approved
### References
- Source reports: L2:2.1.2.md, L2:2.1.3.md
- Related findings: None
- ASVS sections: 2.1.2, 2.1.3
- CWE: CWE-1059
### Priority
Low
---
--
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]
