You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tooling.apache.org by "asf-tooling (via GitHub)" <gi...@apache.org> on 2026/04/03 19:48:51 UTC
[I] Documentation Missing Cross-Entity Business Logic Validation Rules (tooling-trusted-releases)
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: dev-unsubscribe@tooling.apache.org.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tooling.apache.org
For additional commands, e-mail: dev-help@tooling.apache.org
Re: [I] Documentation Missing Cross-Entity Business Logic Validation Rules (tooling-trusted-releases)
Posted by "sbp (via GitHub)" <gi...@apache.org>.
sbp commented on issue #1104:
URL: https://github.com/apache/tooling-trusted-releases/issues/1104#issuecomment-4269528379
This was extremely trivial, so I've done it early. Resolved by 9a4c0a9566a755fb60d9f80f65f7962335a590d5.
--
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: dev-unsubscribe@tooling.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tooling.apache.org
For additional commands, e-mail: dev-help@tooling.apache.org
Re: [I] Documentation Missing Cross-Entity Business Logic Validation Rules (tooling-trusted-releases)
Posted by "sbp (via GitHub)" <gi...@apache.org>.
sbp closed issue #1104: Documentation Missing Cross-Entity Business Logic Validation Rules
URL: https://github.com/apache/tooling-trusted-releases/issues/1104
--
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: dev-unsubscribe@tooling.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tooling.apache.org
For additional commands, e-mail: dev-help@tooling.apache.org