Re: [I] General Library Update Timeframe Is Enforced but Undocumented as Policy (tooling-trusted-releases)

["asf-tooling (via GitHub)" <gi...@apache.org>]

asf-tooling commented on issue #1132:
URL: https://github.com/apache/tooling-trusted-releases/issues/1132#issuecomment-4407497112

   <!-- gofannon-issue-triage-bot v2 -->
   
   **Automated triage** — analyzed at `main@751c2146`
   
   **Type:** `documentation`  •  **Classification:** `actionable`  •  **Confidence:** `high`
   **Application domain(s):** `infrastructure`
   
   ### Summary
   The issue identifies that a 30-day dependency freshness policy is enforced in code (`_MAX_AGE_DAYS=30` in `scripts/check_when_dependencies_updated.py`) but is not documented anywhere. Additionally, the pre-commit hook description in `.pre-commit-config.yaml` references 'ASVS 15.2.1' when the reporter claims the correct section is 'ASVS 15.1.1'. The fix involves adding policy documentation to `SECURITY.md`, correcting the ASVS reference, and adding a code comment. No prior discussion exists on this issue.
   
   ### Where new code would go
   - `SECURITY.md` — after 'Supported versions' section
     Adding a 'Dependency Update Policy' section documenting the 30-day maximum age, rationale, and enforcement mechanism.
   
   ### Proposed approach
   Three small changes are needed: (1) Add a 'Dependency Update Policy' section to `SECURITY.md` that documents the 30-day maximum age, explains the rationale (balancing stability with security freshness per ASVS 15.1.1), and describes the automated enforcement mechanism. (2) Correct the ASVS reference in `.pre-commit-config.yaml` from '15.2.1' to '15.1.1'. (3) Add a brief code comment in `scripts/check_when_dependencies_updated.py` above the `_MAX_AGE_DAYS` constant referencing the policy in SECURITY.md. This is a low-effort documentation improvement (~1 hour as estimated by the reporter).
   
   ### Suggested patches
   
   #### `SECURITY.md`
   Add documented dependency update policy section as required by ASVS 15.1.1
   
   ````diff
   --- a/SECURITY.md
   +++ b/SECURITY.md
   @@ -41,3 +41,18 @@
    ## Supported versions
    
    ATR is a continuously deployed service. We address security issues in the current production version. There are no separately maintained release branches at this time.
   +
   +## Dependency update policy
   +
   +### General library updates (ASVS 15.1.1)
   +
   +- **Maximum age:** 30 days
   +- **Rationale:** Balances stability with security freshness, ensuring known vulnerabilities in dependencies are addressed promptly while avoiding unnecessary churn from bleeding-edge updates.
   +- **Enforcement:** An automated pre-commit hook (`check-when-dependencies-updated`) checks the `exclude-newer` timestamp in `uv.lock` on every commit.
   +- **Verification:** If the lock file's `exclude-newer` timestamp is older than 30 days, the commit is rejected with instructions to run `make update-deps`.
   +- **Update procedure:** Run `make update-deps` to refresh the lock file with the latest compatible dependency versions.
   +
   +### Vulnerability remediation
   +
   +Dependencies with known vulnerabilities are checked via `pip-audit` in pre-commit hooks. Critical vulnerabilities should be addressed immediately regardless of the general update cycle.
   ````
   
   #### `.pre-commit-config.yaml`
   Correct the ASVS reference from 15.2.1 to 15.1.1
   
   ````diff
   --- a/.pre-commit-config.yaml
   +++ b/.pre-commit-config.yaml
   @@ -147,7 +147,7 @@
    
        - id: check-when-dependencies-updated
          name: check when dependencies were updated
   -      description: Verify that dependencies were updated within the configured timeframe, for ASVS 15.2.1
   +      description: Verify that dependencies were updated within the configured timeframe, for ASVS 15.1.1
          entry: uv run --frozen python scripts/check_when_dependencies_updated.py
          language: system
          pass_filenames: false
   ````
   
   #### `scripts/check_when_dependencies_updated.py`
   Add code comment referencing the policy document and ASVS section
   
   ````diff
   --- a/scripts/check_when_dependencies_updated.py
   +++ b/scripts/check_when_dependencies_updated.py
   @@ -23,6 +23,8 @@
    import sys
    from typing import Final
    
   +# Maximum dependency age per ASVS 15.1.1.
   +# See SECURITY.md "Dependency update policy" for rationale.
    _MAX_AGE_DAYS: Final[int] = 30
   ````
   
   ### Open questions
   - Is ASVS 15.1.1 definitely the correct section for general library update timeliness? The issue states the current reference to 15.2.1 is wrong, but this should be verified against the ASVS standard. (15.2.1 might relate to a different aspect of dependency management.)
   - Should the policy document live in SECURITY.md or in a separate file like `docs/dependency-remediation-policy.md`? The issue suggests either location; SECURITY.md was chosen here for proximity to other security policies.
   - The issue mentions 'Unit test verifying the fix' as an acceptance criterion - it's unclear what should be unit-tested here beyond the existing script behavior. The ASVS reference and documentation are not testable via unit tests.
   
   ### Files examined
   - `scripts/check_when_dependencies_updated.py`
   - `.pre-commit-config.yaml`
   - `SECURITY.md`
   - `.pre-commit-heavy.yaml`
   - `.pre-commit-light.yaml`
   - `DEVELOPMENT.md`
   - `BUILD.md`
   - `README.md`
   
   ### Related issues
   This issue appears related to: #1133.
   
   _Both concern dependency management policies and security requirements, with #1132 about undocumented policy enforcement and #1133 about pre-release dependencies in production_
   
   ---
   *Draft from a triage agent. A human reviewer should validate before merging any change. The agent did not run tests or verify diffs apply.*


-- 
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