github-security-report 0.1.0__tar.gz → 0.2.0__tar.gz

{github_security_report-0.1.0 → github_security_report-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: github-security-report
-Version: 0.1.0
+Version: 0.2.0
 Summary: Security and quality reporting across GitHub organisations
 Project-URL: Homepage, https://github.com/lfreleng-actions/github-security-report-action
 Project-URL: Repository, https://github.com/lfreleng-actions/github-security-report-action
@@ -34,9 +34,9 @@ Provides-Extra: dev
 Requires-Dist: mypy==2.1.0; extra == 'dev'
 Requires-Dist: pytest-asyncio==1.4.0; extra == 'dev'
 Requires-Dist: pytest-cov==7.1.0; extra == 'dev'
-Requires-Dist: pytest==9.0.3; extra == 'dev'
+Requires-Dist: pytest==9.1.0; extra == 'dev'
 Requires-Dist: respx==0.23.1; extra == 'dev'
-Requires-Dist: ruff==0.15.16; extra == 'dev'
+Requires-Dist: ruff==0.15.17; extra == 'dev'
 Requires-Dist: syrupy==5.3.2; extra == 'dev'
 Requires-Dist: types-jsonschema==4.26.0.20260518; extra == 'dev'
 Requires-Dist: types-pyyaml==6.0.12.20250915; extra == 'dev'
@@ -86,10 +86,13 @@ tables (org mode):
 - **Dependabot** — three tables: repositories with vulnerability **alerts not
   enabled**, repositories with **security updates not enabled**, and ecosystems
   with no update `cooldown` configured (mandatory; any value passes).
-- **Releases / Tagging** — repositories overdue a release or tag, ranked by a
-  hidden compound staleness score. Repositories younger than
-  `release_min_age_days` (default 28; `0` includes all) and those in
-  `releases_exclude` are omitted.
+- **Releases / Tagging** — repositories overdue a release or tag, ranked by
+  release/tag staleness (repository age never affects ordering; a repository
+  with no release or tag ranks highest). Repositories younger than
+  `repo_min_age_days` (default 28; `0` includes all) and those in
+  `releases_exclude` are omitted. Set `release_max_age_days` to only flag
+  repositories whose newest release or tag is older than that many days
+  (default `0` = flag every eligible repository).
 
 ## Operating modes
 
@@ -109,11 +112,20 @@ Repo mode needs nothing beyond the workflow's ephemeral `GITHUB_TOKEN`. Org mode
 needs a Personal Access Token; choose **one** of the two options below depending
 on how many organisations the report covers.
 
-All required access is **read-only**. The tool degrades any read it is not
-permitted to make to an "unknown" status rather than reporting a repository as
-clean, so an under-scoped token surfaces as unknowns in the report instead of
+Almost all required access is **read-only**. The tool degrades any read it is
+not permitted to make to an "unknown" status rather than reporting a repository
+as clean, so an under-scoped token surfaces as unknowns in the report instead of
 silently wrong results — start minimal and widen if you see unknowns.
 
+The **one** exception is organisation-ruleset coverage. GitHub gates the
+org-rulesets endpoint behind an org-admin permission (classic `admin:org` scope,
+or fine-grained Administration **write**), even though the tool only reads it.
+That coverage is **optional**: it detects tools enforced through an org ruleset
+(for example a required-workflow or code-scanning ruleset). Without it that one
+signal is skipped and every other part of the report is unaffected, so the
+minimal tokens below omit it. Grant the org-admin permission only if you want
+ruleset-based tool coverage.
+
 ### Single organisation — fine-grained PAT
 
 A fine-grained PAT is bound to one resource owner, so it works for a report
@@ -131,14 +143,15 @@ organisation and **Repository access** set to *All repositories*, then grant:
 | Secret scanning alerts | Open secret-scanning alerts |
 | Administration | Dependabot enablement + security-updates status, and effective branch rules |
 
-**Organization permissions** (Read-only):
+**Organization permissions:**
 
-| Permission | Used for |
-| ---------- | -------- |
-| Administration | Organisation rulesets (detect tools enabled via a required workflow) |
+| Permission | Access | Used for |
+| ---------- | ------ | -------- |
+| Administration | Read and write | *Optional* — organisation rulesets (detect tools enforced through an org ruleset). GitHub gates this endpoint behind Administration **write**; omit it to keep the token read-only and skip ruleset-based tool coverage. |
 
-> A fine-grained token cannot span organisations. For a report covering more
-> than one org, use a classic PAT (below).
+> Read-only is enough for everything except the optional ruleset coverage
+> above. A fine-grained token cannot span organisations. For a report covering
+> more than one org, use a classic PAT (below).
 
 ### Multiple organisations — classic PAT
 
@@ -150,7 +163,8 @@ organisations. Grant these scopes:
 | ----- | -------- |
 | `repo` | Repository data, including private repositories |
 | `security_events` | Code scanning, secret scanning, and Dependabot alerts (org-bulk and per-repo) |
-| `read:org` | Listing organisation repositories and reading organisation rulesets |
+| `read:org` | Listing organisation repositories |
+| `admin:org` | *Optional* — reading organisation rulesets for ruleset-based tool coverage. GitHub gates `GET /orgs/{org}/rulesets` behind the full `admin:org` scope; `read:org` and `write:org` return 404. Omit it to skip that one signal; everything else is unaffected. |
 
 > For organisations that enforce SSO, the PAT must be **SSO-authorised** for
 > each target organisation, or the org-level endpoints return `403` (reported as
@@ -207,7 +221,8 @@ environment-variable name, never embedded.
     "top_n_slack": 10,
     "include_archived": false,
     "include_test": false,
-    "release_min_age_days": 28
+    "repo_min_age_days": 28,
+    "release_max_age_days": 0
   },
   "organizations": [
     {
@@ -226,12 +241,29 @@ environment-variable name, never embedded.
 `top_n` controls how many offenders are shown per signal. It is the shared
 default for all three outputs; set any of `top_n_report` (GitHub Pages),
 `top_n_cli` (terminal), or `top_n_slack` (Slack digest) to override an
-individual output. Each can also be set at the CLI with `--top-n`,
+individual output. Set a value to `0` to remove the limit entirely and show
+every offender. Each can also be set at the CLI with `--top-n`,
 `--top-n-report`, `--top-n-cli`, and `--top-n-slack`.
 
-`report.release_min_age_days` (default `28`, `0` = include all) and the per-org
-`releases_exclude` tune the Releases / Tagging section; they can be overridden
-locally with `--release-min-age-days` and the repeatable `--releases-exclude`.
+The Releases / Tagging section has two independent freshness levers:
+
+- `report.repo_min_age_days` (default `28`, `0` = include all) is a grace
+  period that omits **brand-new repositories** — those *created* within that
+  many days — before a release or tag is expected of them. CLI:
+  `--repo-min-age-days`.
+- `report.release_max_age_days` (default `0` = flag everything) is the
+  release-staleness threshold: a repository is only flagged when its newest
+  release **or** tag is older than that many days (a repository with neither is
+  always flagged). Raise it to match your release cadence so actively released
+  repositories drop out of the table. CLI: `--release-max-age-days`.
+
+The per-org `releases_exclude` (CLI `--releases-exclude`, repeatable) drops
+named repositories from the section entirely.
+
+> The former `release_min_age_days` key was a misleading name for
+> `repo_min_age_days` (it gates *repository* age, not *release* age). It is
+> still accepted as a deprecated alias and emits a warning; prefer
+> `repo_min_age_days`.
 
 The per-org `exclude` list removes repositories from analysis entirely; they are
 reported as **excluded** (distinct from "not enabled"), so an intentional
@@ -276,10 +308,10 @@ and the Slack **bot token** is consumed by the workflow, not the CLI.
 | `output_dir` | No | — | Directory for Pages output (org mode) |
 | `pages_url` | No | — | Published Pages URL (used in the Slack link) |
 | `slack_channel` | No | — | Slack channel ID; overrides the config `slack.channel` (e.g. the `SLACK_CHANNEL_ID` variable) |
-| `top_n` | No | `10` | Offenders per signal across all outputs (shared default) |
-| `top_n_report` | No | — | Offenders per signal in the GitHub Pages output (overrides `top_n`) |
-| `top_n_cli` | No | — | Offenders per signal in the terminal output (overrides `top_n`) |
-| `top_n_slack` | No | — | Offenders per signal in the Slack digest (overrides `top_n`) |
+| `top_n` | No | `10` | Offenders per signal across all outputs (shared default; `0` = no limit) |
+| `top_n_report` | No | — | Offenders per signal in the GitHub Pages output (`0` = no limit; overrides `top_n`) |
+| `top_n_cli` | No | — | Offenders per signal in the terminal output (`0` = no limit; overrides `top_n`) |
+| `top_n_slack` | No | — | Offenders per signal in the Slack digest (`0` = no limit; overrides `top_n`) |
 | `fail_threshold` | No | `none` | `none`/`low`/`medium`/`high`/`critical`/`any` (repo mode) |
 | `force_notify` | No | `false` | Post to Slack regardless of `report_day` |
 | `tool_version` | No | `0.1.0` | Published PyPI version (ignored on pull requests) |
@@ -309,6 +341,46 @@ uvx github-security-report report
 uvx github-security-report report --org lfreleng-actions
 ```
 
+## Bulk Remediation Scripts
+
+The report ends with **nag lists** — repositories where a supported feature is
+switched off. Where GitHub exposes the relevant toggle through its REST API,
+the [`scripts/`](scripts/) directory ships standalone helpers that clear a whole
+nag list in one pass instead of clicking through each repository's settings.
+They reuse the tool's own scoping rules
+([`src/github_security_report/scope.py`](src/github_security_report/scope.py)),
+so they act on exactly the repositories the report does. See
+[`scripts/README.md`](scripts/README.md) for full details.
+
+Each script is a self-contained [PEP 723](https://peps.python.org/pep-0723/)
+program: `uv run` resolves its inline dependencies on the fly — no project
+install required.
+
+### `enable_dependabot_security_updates.py`
+
+Enables **Dependabot security updates** (and the prerequisite alerts) across an
+organisation, clearing the "Dependabot: Security Updates" nag list. It reads
+the current state of each repository, enables the feature where it is off, and
+verifies the result.
+
+```bash
+# An org-admin token is required (classic PAT with repo admin / admin:org).
+source ~/.secrets.github.classic.god   # exports $GITHUB_TOKEN
+
+# Dry run (default): preview every change, touch nothing.
+uv run scripts/enable_dependabot_security_updates.py \
+  --config ~/.config/github-security-report/config.json
+
+# Apply: switch the feature on for every in-scope repository.
+uv run scripts/enable_dependabot_security_updates.py \
+  --config ~/.config/github-security-report/config.json --apply
+```
+
+`--config` reads the organisation name and exclusions straight from the
+reporting tool's JSON config, so the script and the report never drift. The
+operation is **dry-run by default** (these are privileged writes) and reversible
+via `DELETE /repos/{owner}/{repo}/automated-security-fixes`.
+
 ## Development
 
 ```bash

{github_security_report-0.1.0 → github_security_report-0.2.0}/README.md

@@ -42,10 +42,13 @@ tables (org mode):
 - **Dependabot** — three tables: repositories with vulnerability **alerts not
   enabled**, repositories with **security updates not enabled**, and ecosystems
   with no update `cooldown` configured (mandatory; any value passes).
-- **Releases / Tagging** — repositories overdue a release or tag, ranked by a
-  hidden compound staleness score. Repositories younger than
-  `release_min_age_days` (default 28; `0` includes all) and those in
-  `releases_exclude` are omitted.
+- **Releases / Tagging** — repositories overdue a release or tag, ranked by
+  release/tag staleness (repository age never affects ordering; a repository
+  with no release or tag ranks highest). Repositories younger than
+  `repo_min_age_days` (default 28; `0` includes all) and those in
+  `releases_exclude` are omitted. Set `release_max_age_days` to only flag
+  repositories whose newest release or tag is older than that many days
+  (default `0` = flag every eligible repository).
 
 ## Operating modes
 
@@ -65,11 +68,20 @@ Repo mode needs nothing beyond the workflow's ephemeral `GITHUB_TOKEN`. Org mode
 needs a Personal Access Token; choose **one** of the two options below depending
 on how many organisations the report covers.
 
-All required access is **read-only**. The tool degrades any read it is not
-permitted to make to an "unknown" status rather than reporting a repository as
-clean, so an under-scoped token surfaces as unknowns in the report instead of
+Almost all required access is **read-only**. The tool degrades any read it is
+not permitted to make to an "unknown" status rather than reporting a repository
+as clean, so an under-scoped token surfaces as unknowns in the report instead of
 silently wrong results — start minimal and widen if you see unknowns.
 
+The **one** exception is organisation-ruleset coverage. GitHub gates the
+org-rulesets endpoint behind an org-admin permission (classic `admin:org` scope,
+or fine-grained Administration **write**), even though the tool only reads it.
+That coverage is **optional**: it detects tools enforced through an org ruleset
+(for example a required-workflow or code-scanning ruleset). Without it that one
+signal is skipped and every other part of the report is unaffected, so the
+minimal tokens below omit it. Grant the org-admin permission only if you want
+ruleset-based tool coverage.
+
 ### Single organisation — fine-grained PAT
 
 A fine-grained PAT is bound to one resource owner, so it works for a report
@@ -87,14 +99,15 @@ organisation and **Repository access** set to *All repositories*, then grant:
 | Secret scanning alerts | Open secret-scanning alerts |
 | Administration | Dependabot enablement + security-updates status, and effective branch rules |
 
-**Organization permissions** (Read-only):
+**Organization permissions:**
 
-| Permission | Used for |
-| ---------- | -------- |
-| Administration | Organisation rulesets (detect tools enabled via a required workflow) |
+| Permission | Access | Used for |
+| ---------- | ------ | -------- |
+| Administration | Read and write | *Optional* — organisation rulesets (detect tools enforced through an org ruleset). GitHub gates this endpoint behind Administration **write**; omit it to keep the token read-only and skip ruleset-based tool coverage. |
 
-> A fine-grained token cannot span organisations. For a report covering more
-> than one org, use a classic PAT (below).
+> Read-only is enough for everything except the optional ruleset coverage
+> above. A fine-grained token cannot span organisations. For a report covering
+> more than one org, use a classic PAT (below).
 
 ### Multiple organisations — classic PAT
 
@@ -106,7 +119,8 @@ organisations. Grant these scopes:
 | ----- | -------- |
 | `repo` | Repository data, including private repositories |
 | `security_events` | Code scanning, secret scanning, and Dependabot alerts (org-bulk and per-repo) |
-| `read:org` | Listing organisation repositories and reading organisation rulesets |
+| `read:org` | Listing organisation repositories |
+| `admin:org` | *Optional* — reading organisation rulesets for ruleset-based tool coverage. GitHub gates `GET /orgs/{org}/rulesets` behind the full `admin:org` scope; `read:org` and `write:org` return 404. Omit it to skip that one signal; everything else is unaffected. |
 
 > For organisations that enforce SSO, the PAT must be **SSO-authorised** for
 > each target organisation, or the org-level endpoints return `403` (reported as
@@ -163,7 +177,8 @@ environment-variable name, never embedded.
     "top_n_slack": 10,
     "include_archived": false,
     "include_test": false,
-    "release_min_age_days": 28
+    "repo_min_age_days": 28,
+    "release_max_age_days": 0
   },
   "organizations": [
     {
@@ -182,12 +197,29 @@ environment-variable name, never embedded.
 `top_n` controls how many offenders are shown per signal. It is the shared
 default for all three outputs; set any of `top_n_report` (GitHub Pages),
 `top_n_cli` (terminal), or `top_n_slack` (Slack digest) to override an
-individual output. Each can also be set at the CLI with `--top-n`,
+individual output. Set a value to `0` to remove the limit entirely and show
+every offender. Each can also be set at the CLI with `--top-n`,
 `--top-n-report`, `--top-n-cli`, and `--top-n-slack`.
 
-`report.release_min_age_days` (default `28`, `0` = include all) and the per-org
-`releases_exclude` tune the Releases / Tagging section; they can be overridden
-locally with `--release-min-age-days` and the repeatable `--releases-exclude`.
+The Releases / Tagging section has two independent freshness levers:
+
+- `report.repo_min_age_days` (default `28`, `0` = include all) is a grace
+  period that omits **brand-new repositories** — those *created* within that
+  many days — before a release or tag is expected of them. CLI:
+  `--repo-min-age-days`.
+- `report.release_max_age_days` (default `0` = flag everything) is the
+  release-staleness threshold: a repository is only flagged when its newest
+  release **or** tag is older than that many days (a repository with neither is
+  always flagged). Raise it to match your release cadence so actively released
+  repositories drop out of the table. CLI: `--release-max-age-days`.
+
+The per-org `releases_exclude` (CLI `--releases-exclude`, repeatable) drops
+named repositories from the section entirely.
+
+> The former `release_min_age_days` key was a misleading name for
+> `repo_min_age_days` (it gates *repository* age, not *release* age). It is
+> still accepted as a deprecated alias and emits a warning; prefer
+> `repo_min_age_days`.
 
 The per-org `exclude` list removes repositories from analysis entirely; they are
 reported as **excluded** (distinct from "not enabled"), so an intentional
@@ -232,10 +264,10 @@ and the Slack **bot token** is consumed by the workflow, not the CLI.
 | `output_dir` | No | — | Directory for Pages output (org mode) |
 | `pages_url` | No | — | Published Pages URL (used in the Slack link) |
 | `slack_channel` | No | — | Slack channel ID; overrides the config `slack.channel` (e.g. the `SLACK_CHANNEL_ID` variable) |
-| `top_n` | No | `10` | Offenders per signal across all outputs (shared default) |
-| `top_n_report` | No | — | Offenders per signal in the GitHub Pages output (overrides `top_n`) |
-| `top_n_cli` | No | — | Offenders per signal in the terminal output (overrides `top_n`) |
-| `top_n_slack` | No | — | Offenders per signal in the Slack digest (overrides `top_n`) |
+| `top_n` | No | `10` | Offenders per signal across all outputs (shared default; `0` = no limit) |
+| `top_n_report` | No | — | Offenders per signal in the GitHub Pages output (`0` = no limit; overrides `top_n`) |
+| `top_n_cli` | No | — | Offenders per signal in the terminal output (`0` = no limit; overrides `top_n`) |
+| `top_n_slack` | No | — | Offenders per signal in the Slack digest (`0` = no limit; overrides `top_n`) |
 | `fail_threshold` | No | `none` | `none`/`low`/`medium`/`high`/`critical`/`any` (repo mode) |
 | `force_notify` | No | `false` | Post to Slack regardless of `report_day` |
 | `tool_version` | No | `0.1.0` | Published PyPI version (ignored on pull requests) |
@@ -265,6 +297,46 @@ uvx github-security-report report
 uvx github-security-report report --org lfreleng-actions
 ```
 
+## Bulk Remediation Scripts
+
+The report ends with **nag lists** — repositories where a supported feature is
+switched off. Where GitHub exposes the relevant toggle through its REST API,
+the [`scripts/`](scripts/) directory ships standalone helpers that clear a whole
+nag list in one pass instead of clicking through each repository's settings.
+They reuse the tool's own scoping rules
+([`src/github_security_report/scope.py`](src/github_security_report/scope.py)),
+so they act on exactly the repositories the report does. See
+[`scripts/README.md`](scripts/README.md) for full details.
+
+Each script is a self-contained [PEP 723](https://peps.python.org/pep-0723/)
+program: `uv run` resolves its inline dependencies on the fly — no project
+install required.
+
+### `enable_dependabot_security_updates.py`
+
+Enables **Dependabot security updates** (and the prerequisite alerts) across an
+organisation, clearing the "Dependabot: Security Updates" nag list. It reads
+the current state of each repository, enables the feature where it is off, and
+verifies the result.
+
+```bash
+# An org-admin token is required (classic PAT with repo admin / admin:org).
+source ~/.secrets.github.classic.god   # exports $GITHUB_TOKEN
+
+# Dry run (default): preview every change, touch nothing.
+uv run scripts/enable_dependabot_security_updates.py \
+  --config ~/.config/github-security-report/config.json
+
+# Apply: switch the feature on for every in-scope repository.
+uv run scripts/enable_dependabot_security_updates.py \
+  --config ~/.config/github-security-report/config.json --apply
+```
+
+`--config` reads the organisation name and exclusions straight from the
+reporting tool's JSON config, so the script and the report never drift. The
+operation is **dry-run by default** (these are privileged writes) and reversible
+via `DELETE /repos/{owner}/{repo}/automated-security-fixes`.
+
 ## Development
 
 ```bash

{github_security_report-0.1.0 → github_security_report-0.2.0}/pyproject.toml

@@ -59,13 +59,13 @@ Issues = "https://github.com/lfreleng-actions/github-security-report-action/issu
 
 [project.optional-dependencies]
 dev = [
-  "pytest==9.0.3",
+  "pytest==9.1.0",
   "pytest-asyncio==1.4.0",
   "pytest-cov==7.1.0",
   "respx==0.23.1",
   "syrupy==5.3.2",
   "mypy==2.1.0",
-  "ruff==0.15.16",
+  "ruff==0.15.17",
   "types-jsonschema==4.26.0.20260518",
   "types-PyYAML==6.0.12.20250915",
 ]
@@ -91,13 +91,13 @@ include = ["src", "README.md", "LICENSE*", "pyproject.toml"]
 
 [dependency-groups]
 dev = [
-  "pytest==9.0.3",
+  "pytest==9.1.0",
   "pytest-asyncio==1.4.0",
   "pytest-cov==7.1.0",
   "respx==0.23.1",
   "syrupy==5.3.2",
   "mypy==2.1.0",
-  "ruff==0.15.16",
+  "ruff==0.15.17",
   "types-jsonschema==4.26.0.20260518",
   "types-PyYAML==6.0.12.20250915",
 ]

{github_security_report-0.1.0 → github_security_report-0.2.0}/scripts/README.md

@@ -5,6 +5,58 @@
 
 # Scripts
 
+## `enable_dependabot_security_updates.py`
+
+Bulk-enables **Dependabot security updates** across an organisation, clearing
+the "Dependabot: Security Updates" nag list the reporting tool produces. It
+drives three REST endpoints per repository:
+
+- `PUT /repos/{owner}/{repo}/vulnerability-alerts` — Dependabot *alerts* (the
+  prerequisite; idempotent).
+- `PUT /repos/{owner}/{repo}/automated-security-fixes` — Dependabot *security
+  updates*.
+- `GET /repos/{owner}/{repo}/automated-security-fixes` — current state, read
+  before and after each change.
+
+By default the scope matches the reporting tool (it reuses the same fork /
+template / archived / test-name / explicit-exclude rules from
+[`../src/github_security_report/scope.py`](../src/github_security_report/scope.py)),
+and likewise skips empty repositories, which the reporting tool already drops
+at the listing stage. The `--include-empty` flag deliberately widens that scope
+to act on empty repositories the report never includes. Pass `--config` to read
+the org name and exclusions straight from the tool's JSON config so the two
+never drift.
+
+It is a self-contained [PEP 723](https://peps.python.org/pep-0723/) script; `uv`
+resolves its inline dependencies (`httpx`, `rich`) on the fly.
+
+### Run
+
+```bash
+# An org-admin token is required (e.g. a classic PAT with repo admin /
+# admin:org). The god token export publishes it as $GITHUB_TOKEN:
+source ~/.secrets.github.classic.god
+
+# Dry run (default): previews exactly what would change, touches nothing.
+uv run scripts/enable_dependabot_security_updates.py \
+  --config ~/.config/github-security-report/config.json
+
+# Apply: switch the feature on for every in-scope repository.
+uv run scripts/enable_dependabot_security_updates.py \
+  --config ~/.config/github-security-report/config.json --apply
+
+# Or drive it from flags, with a different token variable:
+uv run scripts/enable_dependabot_security_updates.py \
+  --org lfreleng-actions --token-env SECURITY_REPORT_PAT \
+  --exclude project-reporting-artifacts --apply
+```
+
+**Dry-run by default.** These are privileged writes, so the script previews
+unless you pass `--apply`. Useful extra flags: `--repo` (operate on named repos
+only, skipping scope), `--limit N`, and `--include-archived` /
+`--include-test` / `--include-empty`. The operation is reversible via
+`DELETE /repos/{owner}/{repo}/automated-security-fixes`.
+
 ## `phase0_capability_spike.py` (throwaway)
 
 A self-contained [PEP 723](https://peps.python.org/pep-0723/) spike that

{github_security_report-0.1.0 → github_security_report-0.2.0}/src/github_security_report/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.0'
-__version_tuple__ = version_tuple = (0, 1, 0)
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)
 
 __commit_id__ = commit_id = None

{github_security_report-0.1.0 → github_security_report-0.2.0}/src/github_security_report/cli.py

@@ -192,7 +192,8 @@ def _load_config(
 async def _run_org(cfg: Config, *, console: Console, output_dir: Path | None,
                    pages_url: str | None, top_n: int | None, force_notify: bool,
                    slack_channel: str | None = None,
-                   release_min_age_days: int | None = None,
+                   repo_min_age_days: int | None = None,
+                   release_max_age_days: int | None = None,
                    releases_exclude: tuple[str, ...] | None = None,
                    top_n_report: int | None = None,
                    top_n_cli: int | None = None,
@@ -206,8 +207,12 @@ async def _run_org(cfg: Config, *, console: Console, output_dir: Path | None,
             return 2
         # CLI overrides win over config for the Releases/Tagging controls.
         report_cfg = org_cfg.report
-        if release_min_age_days is not None:
-            report_cfg = replace(report_cfg, release_min_age_days=release_min_age_days)
+        if repo_min_age_days is not None:
+            report_cfg = replace(report_cfg, repo_min_age_days=repo_min_age_days)
+        if release_max_age_days is not None:
+            report_cfg = replace(
+                report_cfg, release_max_age_days=release_max_age_days
+            )
         effective_cfg = org_cfg
         if releases_exclude is not None:
             effective_cfg = replace(org_cfg, releases_exclude=releases_exclude)
@@ -226,6 +231,15 @@ async def _run_org(cfg: Config, *, console: Console, output_dir: Path | None,
             return top_n
         return int(getattr(org_cfg.report, attr))
 
+    def _most_generous(limits: list[int]) -> int:
+        # 0 means "no limit", so it is the most generous value of all; otherwise
+        # the largest positive cap wins. Without this, max() would treat 0 as
+        # the smallest limit and silently re-impose a cap on an org that asked
+        # for everything when it shares a channel with a capped org.
+        if any(limit <= 0 for limit in limits):
+            return 0
+        return max(limits)
+
     for org_cfg, org_report in pairs:
         term_render.render_org(
             org_report, console, top_n=_limit(org_cfg, top_n_cli, "cli_top_n")
@@ -276,8 +290,8 @@ async def _run_org(cfg: Config, *, console: Console, output_dir: Path | None,
         slack_render.render_payload(
             [report for _, report in items],
             channel=channel,
-            top_n=max(
-                _limit(oc, top_n_slack, "slack_top_n") for oc, _ in items
+            top_n=_most_generous(
+                [_limit(oc, top_n_slack, "slack_top_n") for oc, _ in items]
             ),
             pages_url=pages_url,
         )
@@ -358,13 +372,14 @@ def report(
     output_dir: str | None = typer.Option(None, "--output-dir", "-o", help="Directory for Pages output (org mode)."),
     pages_url: str | None = typer.Option(None, "--pages-url", help="GitHub Pages URL for the Slack link."),
     slack_channel: str | None = typer.Option(None, "--slack-channel", help="Slack channel ID; overrides config slack.channel (e.g. SLACK_CHANNEL_ID)."),
-    top_n: int | None = typer.Option(None, "--top-n", help="Offenders shown per signal across all outputs (default: config, else 10). Overridden per output by the flags below."),
-    top_n_report: int | None = typer.Option(None, "--top-n-report", help="Offenders per signal in the GitHub Pages output (overrides --top-n)."),
-    top_n_cli: int | None = typer.Option(None, "--top-n-cli", help="Offenders per signal in the terminal output (overrides --top-n)."),
-    top_n_slack: int | None = typer.Option(None, "--top-n-slack", help="Offenders per signal in the Slack digest (overrides --top-n)."),
+    top_n: int | None = typer.Option(None, "--top-n", help="Offenders shown per signal across all outputs (0 = no limit; default: config, else 10). Overridden per output by the flags below."),
+    top_n_report: int | None = typer.Option(None, "--top-n-report", help="Offenders per signal in the GitHub Pages output (0 = no limit; overrides --top-n)."),
+    top_n_cli: int | None = typer.Option(None, "--top-n-cli", help="Offenders per signal in the terminal output (0 = no limit; overrides --top-n)."),
+    top_n_slack: int | None = typer.Option(None, "--top-n-slack", help="Offenders per signal in the Slack digest (0 = no limit; overrides --top-n)."),
     fail_threshold: str = typer.Option("none", "--fail-threshold", help="none|low|medium|high|critical|any (repo mode)."),
     force_notify: bool = typer.Option(False, "--force-notify", help="Post to Slack regardless of report_day."),
-    release_min_age_days: int | None = typer.Option(None, "--release-min-age-days", help="Exclude repos created within N days from Releases/Tagging (0 = include all; default: config, else 28)."),
+    repo_min_age_days: int | None = typer.Option(None, "--repo-min-age-days", "--release-min-age-days", help="Exclude repos created within N days from Releases/Tagging (0 = include all; default: config, else 28). --release-min-age-days is a deprecated alias."),
+    release_max_age_days: int | None = typer.Option(None, "--release-max-age-days", help="Flag a repo in Releases/Tagging only when its newest release or tag is older than N days (0 = flag every eligible repo; default: config, else 0)."),
     releases_exclude: list[str] | None = typer.Option(None, "--releases-exclude", help="Repository name to omit from the Releases/Tagging table (repeatable; overrides config)."),
     no_color: bool = typer.Option(False, "--no-color", help="Disable coloured output."),
 ) -> None:
@@ -372,22 +387,25 @@ def report(
     plain = no_color or bool(os.environ.get("CI")) or not sys.stdout.isatty()
     console = Console(no_color=plain, highlight=False)
 
-    # Match the config schema (top_n minimum is 1): reject a non-positive
-    # override at the boundary rather than rendering an empty/odd digest.
+    # Match the config schema (top_n minimum is 0): reject a negative override
+    # at the boundary. 0 is permitted and disables the limit (show everything).
     for name, value in (
         ("--top-n", top_n),
         ("--top-n-report", top_n_report),
         ("--top-n-cli", top_n_cli),
         ("--top-n-slack", top_n_slack),
     ):
-        if value is not None and value < 1:
-            console.print(f"[red]{name} must be 1 or greater[/red]")
+        if value is not None and value < 0:
+            console.print(f"[red]{name} must be 0 or greater (0 = no limit)[/red]")
             raise typer.Exit(2)
 
-    # Match the config schema (release_min_age_days minimum is 0): reject a
-    # negative override at the boundary.
-    if release_min_age_days is not None and release_min_age_days < 0:
-        console.print("[red]--release-min-age-days must be 0 or greater[/red]")
+    # Match the config schema (minimum is 0): reject negative overrides at the
+    # boundary.
+    if repo_min_age_days is not None and repo_min_age_days < 0:
+        console.print("[red]--repo-min-age-days must be 0 or greater[/red]")
+        raise typer.Exit(2)
+    if release_max_age_days is not None and release_max_age_days < 0:
+        console.print("[red]--release-max-age-days must be 0 or greater[/red]")
         raise typer.Exit(2)
 
     cfg = _load_config(config_file, config_data, org, token_env, console=console)
@@ -421,7 +439,8 @@ def report(
                 output_dir=Path(output_dir) if output_dir else None,
                 pages_url=pages_url, top_n=top_n, force_notify=force_notify,
                 slack_channel=slack_channel or None,
-                release_min_age_days=release_min_age_days,
+                repo_min_age_days=repo_min_age_days,
+                release_max_age_days=release_max_age_days,
                 releases_exclude=tuple(releases_exclude) if releases_exclude else None,
                 top_n_report=top_n_report,
                 top_n_cli=top_n_cli,