From 9ea9025364cf40d3ebce00fb9fb0b75e18526bda Mon Sep 17 00:00:00 2001 From: CoderDeltaLAN Date: Fri, 19 Jun 2026 09:57:50 +0100 Subject: [PATCH] docs: record dependency graph and Dependabot settings --- CHANGELOG.md | 1 + docs/DEPENDABOT-DEPENDENCY-GRAPH.md | 98 ++++++++++++++++++++++++ docs/SECURITY-SUPPLY-CHAIN-EVALUATION.md | 44 +++++------ 3 files changed, 118 insertions(+), 25 deletions(-) create mode 100644 docs/DEPENDABOT-DEPENDENCY-GRAPH.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 036b294..1a537f1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ This project has a published GitHub Release line, but no stable support or API g ### Added +- Added a dependency graph and Dependabot settings record with manual GitHub UI evidence and deferred version-update policy. - Added a private vulnerability reporting verification record and documented that GitHub private vulnerability reporting is enabled after manual UI verification. - Added a dedicated CodeQL workflow for Python code scanning without changing the protected CI required check name. - Added a read-only security and supply-chain evaluation record for CodeQL, private vulnerability reporting, Dependabot, Scorecard, and GitHub Actions pinning. diff --git a/docs/DEPENDABOT-DEPENDENCY-GRAPH.md b/docs/DEPENDABOT-DEPENDENCY-GRAPH.md new file mode 100644 index 0000000..b0c0fad --- /dev/null +++ b/docs/DEPENDABOT-DEPENDENCY-GRAPH.md @@ -0,0 +1,98 @@ +# Dependency Graph and Dependabot Settings + +Status: manual GitHub UI verification record. +Scope: post-v0.3.0 maintenance hardening. +Branch: `security/evaluate-dependabot-dependency-graph`. +Date: 2026-06-19. + +This document records GitHub repository security settings that affect dependency visibility and Dependabot behavior for `agent-rules-kit`. + +It is not a security guarantee. It does not make `agent-rules-kit` a dependency scanner, vulnerability scanner, or repository security product. + +## Evidence rules + +GitHub repository settings are treated as manual UI evidence in this record. + +In the GitHub `Settings` -> `Advanced Security` page: + +- a `Disable` button means the setting is currently enabled; +- an `Enable` button means the setting is currently disabled; +- a `Disabled` dropdown value means the setting is currently disabled. + +The GitHub REST API output was treated as best-effort evidence only. In this phase, the `security_and_analysis`, Dependabot alerts, and SBOM API checks did not provide clear positive evidence for every setting, so the GitHub UI remains the source for the manual setting claims below. + +## Current repository setting record + +| Setting | Status recorded | Evidence | Notes | +| --- | --- | --- | --- | +| Private vulnerability reporting | Enabled | Advanced Security UI showed `Disable` | Documented separately in `docs/PRIVATE-VULNERABILITY-REPORTING.md`. | +| Dependency graph | Enabled | Advanced Security UI showed `Disable` | Required baseline for dependency visibility and Dependabot alerting. | +| Automatic dependency submission | Disabled / deferred | Advanced Security UI showed `Disabled` | Deferred because the current project has only `pyproject.toml` as a dependency manifest and no lockfile or complex build-time dependency submission need. | +| Dependabot alerts | Enabled | Advanced Security UI showed `Disable` | Alerts depend on dependency graph coverage and GitHub Advisory Database data. | +| Dependabot rules | Present, not fully evaluated | Advanced Security UI showed `1 rule enabled` | This record does not claim what the rule does because the rule content was not inspected. | +| Dependabot malware alerts | Not claimed enabled in this record | Captured UI evidence showed `Enable` | If later enabled, update this record only after the button shows `Disable`. | +| Dependabot security updates | Enabled | Advanced Security UI showed `Disable` | May open security PRs when Dependabot alerts have available patches. | +| Grouped security updates | Not claimed enabled in this record | Captured UI evidence showed `Enable` | If later enabled, update this record only after the button shows `Disable`. | +| Dependabot version updates | Deferred | Advanced Security UI showed `Enable`; no `.github/dependabot.yml` exists | Version updates require a committed `.github/dependabot.yml` and should be handled in a dedicated phase. | +| CodeQL analysis | Enabled | Advanced Security UI showed CodeQL advanced setup and recent scan | Additional signal only; not a guarantee. | +| Copilot Autofix | Enabled as suggestion source | Advanced Security UI showed `On` | Suggestions must not bypass branch, diff, tests, CI, or PR review. | +| Secret Protection | Enabled | Advanced Security UI showed `Disable` | Keep active; this record does not configure custom patterns. | +| Push protection | Enabled | Advanced Security UI showed `Disable` | Keep active; bypasses, if any, require human review. | + +## Dependency graph boundary + +The dependency graph is useful for identifying declared dependencies from supported manifest and lock files and for supporting dependency review and Dependabot alerts. + +For this repository, the only dependency manifest found during the phase was: + +- `pyproject.toml` + +There is no lockfile in the repository in this phase. + +## Dependabot alerts and security updates boundary + +Dependabot alerts and security updates are useful repository-maintenance signals. + +They do not prove that dependencies are safe, complete, current, or free of vulnerabilities. They also do not change the runtime product boundary: + +- no runtime network access; +- no runtime LLM dependency; +- no execution of commands from analyzed repositories; +- no dependency vulnerability scanning feature in `agent-rules-kit` itself. + +Dependabot security updates may open pull requests for vulnerable dependencies with available patches. Those pull requests must follow the normal Always-Green workflow: branch, diff review, checks, PR, CI, and merge by exact head SHA. + +## Deferred Dependabot version updates + +Dependabot version updates are deliberately deferred in this phase. + +Reason: version updates are enabled by committing a `.github/dependabot.yml` file, and they can open normal update PRs even when no vulnerability exists. That is useful, but it is a separate supply-chain maintenance phase, not part of this settings-record phase. + +Expected future branch if accepted: + +- `supply-chain/add-dependabot-version-updates` + +## Deferred automatic dependency submission + +Automatic dependency submission remains deferred. + +Current rationale: + +- simple Python CLI; +- no runtime dependencies; +- no lockfile currently present; +- no complex build-time dependency graph that needs extra submission data. + +Re-evaluate this if the project later adds a lockfile, additional build tooling, runtime dependencies, or a release process that needs richer SBOM/dependency evidence. + +## Review triggers + +Update this record when: + +- `.github/dependabot.yml` is added; +- a lockfile is introduced; +- runtime dependencies are added; +- Dependabot malware alerts or grouped security updates are manually verified as enabled; +- Dependabot rules are opened and documented; +- GitHub changes the Advanced Security UI or API fields used as evidence; +- the release process starts relying on SBOM or dependency submission evidence. diff --git a/docs/SECURITY-SUPPLY-CHAIN-EVALUATION.md b/docs/SECURITY-SUPPLY-CHAIN-EVALUATION.md index acae1be..f9c4a2f 100644 --- a/docs/SECURITY-SUPPLY-CHAIN-EVALUATION.md +++ b/docs/SECURITY-SUPPLY-CHAIN-EVALUATION.md @@ -32,21 +32,15 @@ The publish job needs `id-token: write` for PyPI Trusted Publishing. No static P ## Private vulnerability reporting -Current repository documentation states that private vulnerability reporting has been checked and is currently verified as disabled. +Private vulnerability reporting has since been manually enabled and documented for this repository. -Do not claim private vulnerability reporting is enabled unless the repository setting is explicitly verified as enabled. +Current documentation: -Decision for this phase: - -- do not enable or change private vulnerability reporting in this branch; -- keep SECURITY.md honest about the current disabled state; -- keep the documented public fallback: no secrets, exploit details, private URLs, customer data, or sensitive repository contents should be posted publicly. +- `SECURITY.md` states that private vulnerability reporting is enabled; +- `docs/PRIVATE-VULNERABILITY-REPORTING.md` records the manual GitHub UI verification evidence and limits; +- the setting must still be treated as a disclosure channel, not a security guarantee. -Future enablement candidate: - -- create a separate settings-only phase if the maintainer decides to enable private vulnerability reporting; -- verify the setting after enablement; -- update SECURITY.md, README, and release documentation only after verified evidence exists. +Historical note: this document was originally created as a read-only evaluation before private vulnerability reporting was enabled. That older disabled-state wording is no longer current. ## CodeQL and code scanning @@ -83,29 +77,29 @@ Recommended future CodeQL phase boundaries: Dependabot alerts help identify known vulnerable dependencies when the dependency graph can detect affected packages. -Potential value for this project: +Current repository setting record: -- alerts for development tooling vulnerabilities; -- visibility into dependency risk even with zero runtime dependencies; -- useful because the project has build, lint, test, and publishing tooling. +- dependency graph is manually verified as enabled; +- Dependabot alerts are manually verified as enabled; +- Dependabot security updates are manually verified as enabled; +- Dependabot version updates are deferred because no `.github/dependabot.yml` exists in this phase; +- automatic dependency submission is deferred; +- malware alerts and grouped security updates are not claimed as enabled in this record unless separately verified by a later UI check. + +See `docs/DEPENDABOT-DEPENDENCY-GRAPH.md` for the dedicated settings record. Risks and constraints: - alerts may not cover every issue; - only GitHub-reviewed advisories trigger alerts; - dependency graph coverage depends on supported ecosystems and manifest visibility; -- this does not make agent-rules-kit a dependency vulnerability scanner. - -Decision for this phase: - -- do not enable or configure Dependabot in this branch; -- record Dependabot alerts as a future settings/configuration candidate; -- keep any Dependabot version-update policy separate from vulnerability-alert evaluation. +- this does not make agent-rules-kit a dependency vulnerability scanner; +- Dependabot-created PRs still require normal Always-Green review, checks, CI, and exact-head merge discipline. Recommended future Dependabot phase boundaries: -- first evaluate repository settings and current alert status; -- then decide whether to add `.github/dependabot.yml` for version updates; +- inspect and document the existing Dependabot rule before claiming it as a control; +- decide whether to add `.github/dependabot.yml` for version updates in a separate branch; - do not combine version-update automation with CodeQL, release, or security-policy changes. ## OpenSSF Scorecard