github-security-report 0.10.0__tar.gz → 0.11.0__tar.gz

{github_security_report-0.10.0 → github_security_report-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: github-security-report
-Version: 0.10.0
+Version: 0.11.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
@@ -29,14 +29,14 @@ Requires-Dist: jinja2==3.1.6
 Requires-Dist: jsonschema==4.26.0
 Requires-Dist: pyyaml==6.0.3
 Requires-Dist: rich==15.0.0
-Requires-Dist: typer==0.27.0
+Requires-Dist: typer==0.27.1
 Provides-Extra: dev
 Requires-Dist: mypy==2.3.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.1.1; extra == 'dev'
 Requires-Dist: respx==0.23.1; extra == 'dev'
-Requires-Dist: ruff==0.15.22; extra == 'dev'
+Requires-Dist: ruff==0.16.2; extra == 'dev'
 Requires-Dist: syrupy==5.5.3; extra == 'dev'
 Requires-Dist: types-jsonschema==4.26.0.20260518; extra == 'dev'
 Requires-Dist: types-pyyaml==6.0.12.20250915; extra == 'dev'
@@ -151,6 +151,20 @@ 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.
 
+A token without that permission gets a `404` from the endpoint, which the tool
+reports at **INFO** — so it is invisible unless you pass `--verbose`:
+
+```text
+org rulesets not readable for <org> (status 404); expected unless the token
+carries the optional org-admin permission ...
+```
+
+That line is informational, not a defect. Tools are still detected from the
+code-scanning analyses they upload, so the report is identical unless a
+repository is covered *solely* by a required-workflow ruleset whose workflow has
+never run. A genuinely unexpected failure to read the rulesets (for example a
+`5xx`) is still logged as a warning.
+
 ### Single organisation — fine-grained PAT
 
 A fine-grained PAT is bound to one resource owner, so it works for a report
@@ -166,6 +180,7 @@ organisation and **Repository access** set to *All repositories*, then grant:
 | Dependabot alerts | Open Dependabot vulnerability alerts |
 | Code scanning alerts | CodeQL / Scorecard / zizmor / aislop findings |
 | Secret scanning alerts | Open secret-scanning alerts |
+| Issues | Open issues and their labels (GitHub Issues table) |
 | Administration | Dependabot enablement + security-updates status, and effective branch rules |
 
 **Organization permissions:**
@@ -324,7 +339,8 @@ out of the terminal and Slack while still publishing it to the Markdown and HTML
 Pages output. The valid category keys are: `codeql`, `scorecard`, `zizmor`,
 `aislop`, `dependabot_alerts`, `secret_scanning`, `dependabot_alerts_enabled`,
 `dependabot_updates_enabled`, `dependabot_cooldown`, `releases`,
-`mutable_releases`, `private_vulnerability_reporting`. Like the other `report`
+`mutable_releases`, `private_vulnerability_reporting`, `github_issues`. Like the
+other `report`
 settings, `categories` can be set
 globally and overridden per organisation (overrides merge key-by-key, so
 flipping one output leaves the rest untouched). The machine-readable
@@ -339,6 +355,179 @@ unless every org sharing that channel also disables it (this mirrors the
 most-generous `top_n` rule applied to the same grouping). The terminal, Markdown
 and HTML surfaces are per-org and are not affected by this union.
 
+### Per-category row limits
+
+A category can also set its own `top_n`, capping that one table independently of
+every other. Reach for this when one category is worth showing in full while the
+rest stay short — set it to `0` for no limit at all:
+
+```json
+{
+  "report": {
+    "top_n": 10,
+    "categories": {
+      "releases": { "top_n": 0 },
+      "codeql": { "top_n": 3 }
+    }
+  },
+  "organizations": [{ "name": "lfreleng-actions" }]
+}
+```
+
+Here Releases / Tagging lists every repository, CodeQL shows its worst three, and
+every other category keeps the shared limit of 10. A category's `top_n` applies
+to all four surfaces at once; combine it with `top_n_report` / `top_n_cli` /
+`top_n_slack` to vary the fallback per surface.
+
+The resolution order for one category on one surface, most specific first:
+
+1. `--top-n-report` / `--top-n-cli` / `--top-n-slack` (command line)
+2. `--top-n` (command line)
+3. `report.categories.<key>.top_n` (config)
+4. `report.top_n_report` / `top_n_cli` / `top_n_slack` (config)
+5. `report.top_n` (config, default `10`)
+
+Command-line flags deliberately outrank the per-category configuration: a flag is
+a decision about a single run, so `--top-n 5` caps every category even where the
+config asked for an uncapped one. `0` means "no limit" at every level. In a
+shared Slack channel the most generous value any contributing org configured for
+that category wins, matching the visibility rule above.
+
+### Per-category row ordering
+
+Each table ships a sensible default ordering — largest backlog first, stalest
+release first, and so on. `report.categories.<key>.sort` overrides it with a list
+of column names, evaluated left to right:
+
+```json
+{
+  "report": {
+    "categories": {
+      "github_issues": { "sort": ["untriaged", "bug", "total", "oldest"] }
+    }
+  },
+  "organizations": [{ "name": "lfreleng-actions" }]
+}
+```
+
+That ranks the Issues table by untriaged count, breaking ties on Bug, then on
+total open issues, then on the oldest issue.
+
+- Names match column headers **case-insensitively**, so `untriaged` finds
+  `Untriaged` and a custom `issue_labels` column such as `Regression` works with
+  no extra configuration. `repository` sorts by repository name.
+- **Direction is implicit by type**: numeric columns descend (most first, which
+  is also oldest-first for an age column) and text columns ascend.
+- A leading **`-` forces descending** and **`+` forces ascending**, so
+  `["+total"]` lists the smallest backlogs first.
+- A cell with **no value to sort on** — an `Oldest` of `unknown`, say — stays at
+  the bottom whichever direction you choose. Missing is not the same as small.
+- The repository name is always applied as the final tiebreaker, so rows that
+  are equal under every configured term still order deterministically.
+- An unrecognised column name is logged and skipped rather than failing the run.
+- Omitting `sort` keeps the table's own default ordering. This matters: some
+  defaults rank on values that are never displayed as a column — Releases /
+  Tagging ranks on *missing* release and tag signals — so they cannot be
+  expressed as a column list.
+
+Ordering is resolved once, when the report is built, so every surface and
+`report.json` agree. It applies to the generic tables (GitHub Issues, Releases /
+Tagging, Mutable Releases, the Dependabot posture tables). The severity signal
+tables keep their own ranking, which encodes domain logic a column sort would
+flatten — Scorecard cascades through the worst populated severity rung so a lone
+Critical is never buried by a weaker repository with a lower score.
+
+### GitHub Issues
+
+The `github_issues` category counts each repository's **open issues**, split by
+label into columns. It reads from the same batched GraphQL prefetch as the
+release and Dependabot data, so it costs no extra API requests:
+
+```text
+GitHub Issues
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━┳━━━━━━━━━┳━━━━━━┳━━━━━━━┳━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━┓
+┃ Repository                    ┃ Bug ┃ Feature ┃ Docs ┃ Other ┃ Untriaged ┃ Total ┃  Oldest ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━╇━━━━━━━━━╇━━━━━━╇━━━━━━━╇━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━┩
+│ .github                       │   1 │       0 │    0 │     0 │        10 │    11 │ 16 days │
+│ tag-validate-action           │   0 │       0 │    0 │     0 │         8 │     8 │ 25 days │
+│ security-workflows            │   0 │       5 │    1 │     0 │         0 │     6 │   today │
+│ github-security-report-action │   0 │       0 │    0 │     3 │         1 │     4 │ 52 days │
+│ dependamerge                  │   0 │       1 │    0 │     1 │         1 │     3 │ 52 days │
+├───────────────────────────────┼─────┼─────────┼──────┼───────┼───────────┼───────┼─────────┤
+│ Total                         │   1 │       6 │    1 │     4 │        20 │    32 │         │
+└───────────────────────────────┴─────┴─────────┴──────┴───────┴───────────┴───────┴─────────┘
+  … and 11 more
+  ❌ 16 With open issues
+  ✅ 87 No open issues
+```
+
+That is a real run of `lfreleng-actions` under `top_n: 5`. The totals row sums
+the rows actually **displayed**, matching the offender tables, so it stays
+consistent with a truncated view; `… and 11 more` plus the five listed rows
+reconcile with the `❌ 16` in the footer.
+
+Two columns are always present and are not configurable:
+
+- **Other** — the issue is labelled, but with nothing you asked about.
+- **Untriaged** — the issue has no labels at all. This is the column to watch:
+  an unlabelled issue is one nobody has categorised.
+
+Both names are reserved, as are `Repository`, `Total` and `Oldest`: configuring a
+column with one of those names is rejected, because it would either share a
+counter with the implicit column — stopping the class columns summing to `Total`
+— or duplicate a header, which would also make `sort: ["repository"]` resolve to
+a count column instead of the repository name. Column names must additionally be
+non-blank, unpadded, distinct case-insensitively (`sort` matches them that way,
+and strips its terms), and free of `|`, backticks and control characters, which
+would corrupt the Markdown table or Slack code fence they are rendered into.
+
+The remaining columns come from `report.issue_labels`, which maps a column name
+to the issue labels that count towards it. An issue counts **once**, under the
+first column whose labels it carries, so the columns always sum to the classified
+total. Matching is case-insensitive on the whole label name, so `docs` does not
+swallow an unrelated `docs-needed`. The default is:
+
+```json
+{
+  "report": {
+    "issue_labels": {
+      "Bug": ["bug", "defect"],
+      "Feature": ["feature", "enhancement"],
+      "Docs": ["documentation", "docs"]
+    }
+  },
+  "organizations": [{ "name": "lfreleng-actions" }]
+}
+```
+
+Unlike `ruleset_workflows`, a configured `issue_labels` **replaces** the default
+rather than merging into it — the mapping defines a coherent set of table
+columns, so merging would leave behind default columns you deliberately left out.
+
+Repositories with no open issues are counted in the `✅ No open issues` footer
+rather than listed. Rows rank by total open issues, then by Untriaged. Pull
+requests are **not** counted: the GraphQL `issues` connection excludes them.
+
+> **Accuracy note.** `Total` is exact at any backlog size, as is `Oldest`
+> wherever an age is shown. The label columns are computed from a bounded,
+> oldest-first window of each repository's open issues (25 issues, 5 labels
+> each) that keeps the query well inside GitHub's GraphQL rate-limit budget. A
+> repository whose label breakdown is partial shows a trailing `+` on its
+> `Oldest` cell. That covers a backlog exceeding the issue window, and any issue
+> whose classification a label beyond the label window could have changed —
+> which is every classification except a match on the *first* configured column,
+> since columns are matched in declaration order and an unseen label could
+> belong to an earlier one. An issue whose labels could not be read at all is
+> left out of the class columns entirely rather than counted as `Untriaged`. An
+> `Oldest` of `unknown` means the oldest issue came back unreadable or undated;
+> it can still carry the `+`.
+
+**Permissions.** A fine-grained PAT needs **Issues: read** for this table; a
+classic PAT's `repo` scope already covers it. Without it GitHub serves the query
+with HTTP 200 and this one field null, so affected repositories are reported as
+`❓ Unknown` rather than counted as having no open issues — an unreadable backlog
+is never presented as a clean one.
+
 ### Organisation feature gating
 
 The workflow-driven signals (OpenSSF Scorecard, zizmor, aislop) need

{github_security_report-0.10.0 → github_security_report-0.11.0}/README.md

@@ -107,6 +107,20 @@ 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.
 
+A token without that permission gets a `404` from the endpoint, which the tool
+reports at **INFO** — so it is invisible unless you pass `--verbose`:
+
+```text
+org rulesets not readable for <org> (status 404); expected unless the token
+carries the optional org-admin permission ...
+```
+
+That line is informational, not a defect. Tools are still detected from the
+code-scanning analyses they upload, so the report is identical unless a
+repository is covered *solely* by a required-workflow ruleset whose workflow has
+never run. A genuinely unexpected failure to read the rulesets (for example a
+`5xx`) is still logged as a warning.
+
 ### Single organisation — fine-grained PAT
 
 A fine-grained PAT is bound to one resource owner, so it works for a report
@@ -122,6 +136,7 @@ organisation and **Repository access** set to *All repositories*, then grant:
 | Dependabot alerts | Open Dependabot vulnerability alerts |
 | Code scanning alerts | CodeQL / Scorecard / zizmor / aislop findings |
 | Secret scanning alerts | Open secret-scanning alerts |
+| Issues | Open issues and their labels (GitHub Issues table) |
 | Administration | Dependabot enablement + security-updates status, and effective branch rules |
 
 **Organization permissions:**
@@ -280,7 +295,8 @@ out of the terminal and Slack while still publishing it to the Markdown and HTML
 Pages output. The valid category keys are: `codeql`, `scorecard`, `zizmor`,
 `aislop`, `dependabot_alerts`, `secret_scanning`, `dependabot_alerts_enabled`,
 `dependabot_updates_enabled`, `dependabot_cooldown`, `releases`,
-`mutable_releases`, `private_vulnerability_reporting`. Like the other `report`
+`mutable_releases`, `private_vulnerability_reporting`, `github_issues`. Like the
+other `report`
 settings, `categories` can be set
 globally and overridden per organisation (overrides merge key-by-key, so
 flipping one output leaves the rest untouched). The machine-readable
@@ -295,6 +311,179 @@ unless every org sharing that channel also disables it (this mirrors the
 most-generous `top_n` rule applied to the same grouping). The terminal, Markdown
 and HTML surfaces are per-org and are not affected by this union.
 
+### Per-category row limits
+
+A category can also set its own `top_n`, capping that one table independently of
+every other. Reach for this when one category is worth showing in full while the
+rest stay short — set it to `0` for no limit at all:
+
+```json
+{
+  "report": {
+    "top_n": 10,
+    "categories": {
+      "releases": { "top_n": 0 },
+      "codeql": { "top_n": 3 }
+    }
+  },
+  "organizations": [{ "name": "lfreleng-actions" }]
+}
+```
+
+Here Releases / Tagging lists every repository, CodeQL shows its worst three, and
+every other category keeps the shared limit of 10. A category's `top_n` applies
+to all four surfaces at once; combine it with `top_n_report` / `top_n_cli` /
+`top_n_slack` to vary the fallback per surface.
+
+The resolution order for one category on one surface, most specific first:
+
+1. `--top-n-report` / `--top-n-cli` / `--top-n-slack` (command line)
+2. `--top-n` (command line)
+3. `report.categories.<key>.top_n` (config)
+4. `report.top_n_report` / `top_n_cli` / `top_n_slack` (config)
+5. `report.top_n` (config, default `10`)
+
+Command-line flags deliberately outrank the per-category configuration: a flag is
+a decision about a single run, so `--top-n 5` caps every category even where the
+config asked for an uncapped one. `0` means "no limit" at every level. In a
+shared Slack channel the most generous value any contributing org configured for
+that category wins, matching the visibility rule above.
+
+### Per-category row ordering
+
+Each table ships a sensible default ordering — largest backlog first, stalest
+release first, and so on. `report.categories.<key>.sort` overrides it with a list
+of column names, evaluated left to right:
+
+```json
+{
+  "report": {
+    "categories": {
+      "github_issues": { "sort": ["untriaged", "bug", "total", "oldest"] }
+    }
+  },
+  "organizations": [{ "name": "lfreleng-actions" }]
+}
+```
+
+That ranks the Issues table by untriaged count, breaking ties on Bug, then on
+total open issues, then on the oldest issue.
+
+- Names match column headers **case-insensitively**, so `untriaged` finds
+  `Untriaged` and a custom `issue_labels` column such as `Regression` works with
+  no extra configuration. `repository` sorts by repository name.
+- **Direction is implicit by type**: numeric columns descend (most first, which
+  is also oldest-first for an age column) and text columns ascend.
+- A leading **`-` forces descending** and **`+` forces ascending**, so
+  `["+total"]` lists the smallest backlogs first.
+- A cell with **no value to sort on** — an `Oldest` of `unknown`, say — stays at
+  the bottom whichever direction you choose. Missing is not the same as small.
+- The repository name is always applied as the final tiebreaker, so rows that
+  are equal under every configured term still order deterministically.
+- An unrecognised column name is logged and skipped rather than failing the run.
+- Omitting `sort` keeps the table's own default ordering. This matters: some
+  defaults rank on values that are never displayed as a column — Releases /
+  Tagging ranks on *missing* release and tag signals — so they cannot be
+  expressed as a column list.
+
+Ordering is resolved once, when the report is built, so every surface and
+`report.json` agree. It applies to the generic tables (GitHub Issues, Releases /
+Tagging, Mutable Releases, the Dependabot posture tables). The severity signal
+tables keep their own ranking, which encodes domain logic a column sort would
+flatten — Scorecard cascades through the worst populated severity rung so a lone
+Critical is never buried by a weaker repository with a lower score.
+
+### GitHub Issues
+
+The `github_issues` category counts each repository's **open issues**, split by
+label into columns. It reads from the same batched GraphQL prefetch as the
+release and Dependabot data, so it costs no extra API requests:
+
+```text
+GitHub Issues
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━┳━━━━━━━━━┳━━━━━━┳━━━━━━━┳━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━┓
+┃ Repository                    ┃ Bug ┃ Feature ┃ Docs ┃ Other ┃ Untriaged ┃ Total ┃  Oldest ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━╇━━━━━━━━━╇━━━━━━╇━━━━━━━╇━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━┩
+│ .github                       │   1 │       0 │    0 │     0 │        10 │    11 │ 16 days │
+│ tag-validate-action           │   0 │       0 │    0 │     0 │         8 │     8 │ 25 days │
+│ security-workflows            │   0 │       5 │    1 │     0 │         0 │     6 │   today │
+│ github-security-report-action │   0 │       0 │    0 │     3 │         1 │     4 │ 52 days │
+│ dependamerge                  │   0 │       1 │    0 │     1 │         1 │     3 │ 52 days │
+├───────────────────────────────┼─────┼─────────┼──────┼───────┼───────────┼───────┼─────────┤
+│ Total                         │   1 │       6 │    1 │     4 │        20 │    32 │         │
+└───────────────────────────────┴─────┴─────────┴──────┴───────┴───────────┴───────┴─────────┘
+  … and 11 more
+  ❌ 16 With open issues
+  ✅ 87 No open issues
+```
+
+That is a real run of `lfreleng-actions` under `top_n: 5`. The totals row sums
+the rows actually **displayed**, matching the offender tables, so it stays
+consistent with a truncated view; `… and 11 more` plus the five listed rows
+reconcile with the `❌ 16` in the footer.
+
+Two columns are always present and are not configurable:
+
+- **Other** — the issue is labelled, but with nothing you asked about.
+- **Untriaged** — the issue has no labels at all. This is the column to watch:
+  an unlabelled issue is one nobody has categorised.
+
+Both names are reserved, as are `Repository`, `Total` and `Oldest`: configuring a
+column with one of those names is rejected, because it would either share a
+counter with the implicit column — stopping the class columns summing to `Total`
+— or duplicate a header, which would also make `sort: ["repository"]` resolve to
+a count column instead of the repository name. Column names must additionally be
+non-blank, unpadded, distinct case-insensitively (`sort` matches them that way,
+and strips its terms), and free of `|`, backticks and control characters, which
+would corrupt the Markdown table or Slack code fence they are rendered into.
+
+The remaining columns come from `report.issue_labels`, which maps a column name
+to the issue labels that count towards it. An issue counts **once**, under the
+first column whose labels it carries, so the columns always sum to the classified
+total. Matching is case-insensitive on the whole label name, so `docs` does not
+swallow an unrelated `docs-needed`. The default is:
+
+```json
+{
+  "report": {
+    "issue_labels": {
+      "Bug": ["bug", "defect"],
+      "Feature": ["feature", "enhancement"],
+      "Docs": ["documentation", "docs"]
+    }
+  },
+  "organizations": [{ "name": "lfreleng-actions" }]
+}
+```
+
+Unlike `ruleset_workflows`, a configured `issue_labels` **replaces** the default
+rather than merging into it — the mapping defines a coherent set of table
+columns, so merging would leave behind default columns you deliberately left out.
+
+Repositories with no open issues are counted in the `✅ No open issues` footer
+rather than listed. Rows rank by total open issues, then by Untriaged. Pull
+requests are **not** counted: the GraphQL `issues` connection excludes them.
+
+> **Accuracy note.** `Total` is exact at any backlog size, as is `Oldest`
+> wherever an age is shown. The label columns are computed from a bounded,
+> oldest-first window of each repository's open issues (25 issues, 5 labels
+> each) that keeps the query well inside GitHub's GraphQL rate-limit budget. A
+> repository whose label breakdown is partial shows a trailing `+` on its
+> `Oldest` cell. That covers a backlog exceeding the issue window, and any issue
+> whose classification a label beyond the label window could have changed —
+> which is every classification except a match on the *first* configured column,
+> since columns are matched in declaration order and an unseen label could
+> belong to an earlier one. An issue whose labels could not be read at all is
+> left out of the class columns entirely rather than counted as `Untriaged`. An
+> `Oldest` of `unknown` means the oldest issue came back unreadable or undated;
+> it can still carry the `+`.
+
+**Permissions.** A fine-grained PAT needs **Issues: read** for this table; a
+classic PAT's `repo` scope already covers it. Without it GitHub serves the query
+with HTTP 200 and this one field null, so affected repositories are reported as
+`❓ Unknown` rather than counted as having no open issues — an unreadable backlog
+is never presented as a clean one.
+
 ### Organisation feature gating
 
 The workflow-driven signals (OpenSSF Scorecard, zizmor, aislop) need

{github_security_report-0.10.0 → github_security_report-0.11.0}/pyproject.toml

@@ -45,7 +45,7 @@ keywords = [
 ]
 dependencies = [
   "httpx[http2]==0.28.1",
-  "typer==0.27.0",
+  "typer==0.27.1",
   "rich==15.0.0",
   "jinja2==3.1.6",
   "jsonschema==4.26.0",
@@ -65,7 +65,7 @@ dev = [
   "respx==0.23.1",
   "syrupy==5.5.3",
   "mypy==2.3.0",
-  "ruff==0.15.22",
+  "ruff==0.16.2",
   "types-jsonschema==4.26.0.20260518",
   "types-PyYAML==6.0.12.20250915",
 ]
@@ -97,7 +97,7 @@ dev = [
   "respx==0.23.1",
   "syrupy==5.5.3",
   "mypy==2.3.0",
-  "ruff==0.15.22",
+  "ruff==0.16.2",
   "types-jsonschema==4.26.0.20260518",
   "types-PyYAML==6.0.12.20250915",
 ]

{github_security_report-0.10.0 → github_security_report-0.11.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.10.0'
-__version_tuple__ = version_tuple = (0, 10, 0)
+__version__ = version = '0.11.0'
+__version_tuple__ = version_tuple = (0, 11, 0)
 
 __commit_id__ = commit_id = None

{github_security_report-0.10.0 → github_security_report-0.11.0}/src/github_security_report/categories.py

@@ -40,6 +40,7 @@ class CategoryKey(str, Enum):
     RELEASES = "releases"
     MUTABLE_RELEASES = "mutable_releases"
     PRIVATE_VULNERABILITY_REPORTING = "private_vulnerability_reporting"
+    GITHUB_ISSUES = "github_issues"
 
 
 @dataclass(frozen=True)
@@ -48,7 +49,10 @@ class CategoryMeta:
 
     ``pass_label`` names the healthy state (e.g. ``"Clean"``, ``"Immutable"``)
     and is what the summary footer reports as ``All <pass_label>`` when nothing
-    needs attention. ``fail_label`` names the actionable state for categories
+    needs attention. That collapse wants an adjectival label; a category whose
+    counted wording is a noun phrase ("12 No open issues") sets
+    ``pass_all_label`` to the word that reads correctly after "All" instead.
+    ``fail_label`` names the actionable state for categories
     with a binary pass/fail axis (enablement, cooldown, mutability, release
     freshness); it is ``None`` for the severity-ranked signals, whose offenders
     are enumerated in the table itself rather than as a single failure count.
@@ -63,6 +67,9 @@ class CategoryMeta:
     fail_label: str | None
     url: str
     description: str = ""
+    # Alternative pass wording for the collapsed "All <label>" footer line,
+    # when the counted wording would not read grammatically after "All".
+    pass_all_label: str | None = None
     # The lowest finding severity that counts as a failure for this category.
     # A repository fails (appears as an offender) only when it carries a finding
     # at or above this rung; findings below it fold into the clean count. The
@@ -252,6 +259,23 @@ _CATEGORIES: dict[CategoryKey, CategoryMeta] = {
             "instead of disclosing them publicly."
         ),
     ),
+    CategoryKey.GITHUB_ISSUES: CategoryMeta(
+        key=CategoryKey.GITHUB_ISSUES,
+        title="GitHub Issues",
+        pass_label="No open issues",
+        # "All No open issues" does not parse; the collapsed line reads
+        # "All Clean", matching the other categories' vocabulary.
+        pass_all_label="Clean",
+        fail_label="With open issues",
+        url="https://docs.github.com/en/issues",
+        description=(
+            "Open issues per repository, split by label into the configured "
+            "classes. Issues carrying none of the configured labels count as "
+            "Other; issues with no labels at all count as Untriaged, which is "
+            "the column to watch -- an unlabelled issue has not been triaged. "
+            "Ranked by total open issues, then by Untriaged."
+        ),
+    ),
 }
 
 

github_security_report-0.11.0/src/github_security_report/cli/__init__.py

@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 The Linux Foundation
+"""Command-line entry point.
+
+Wires configuration, scope/mode resolution, collection, and rendering into the
+``github-security-report`` command. Org mode produces Pages/Slack/terminal
+output; repo mode is a degraded PR gate emitting a job summary and outputs.
+See ``docs/BRIEF.md`` sections 9-12.
+
+The command surface is split across:
+
+- :mod:`cli.app` -- the Typer application, options and validation
+- :mod:`cli.modes` -- the org, repo and remediate run modes
+- :mod:`cli.outputs` -- offender limits, category visibility, file writing
+- :mod:`cli.serialise` -- the machine-readable ``report.json`` shape
+"""
+
+from __future__ import annotations
+
+from github_security_report.cli.app import (
+    _version_callback,
+    app,
+    main,
+    remediate,
+    report,
+)
+from github_security_report.cli.modes import (
+    OrgRunOptions,
+    ReleaseOverrides,
+    _abort_network,
+    _load_config,
+    _run_org,
+    _run_remediate,
+    _run_repo,
+)
+from github_security_report.cli.outputs import (
+    TopNLimits,
+    _safe_component,
+    repo_outputs,
+    write_org_files,
+)
+from github_security_report.cli.serialise import _org_to_dict, _table_to_dict
+
+# The package façade: every name previously importable from
+# ``github_security_report.cli`` still is, including the private helpers the
+# tests reach for, so splitting the module changed no caller's import path.
+__all__ = [
+    "OrgRunOptions",
+    "ReleaseOverrides",
+    "TopNLimits",
+    "_abort_network",
+    "_load_config",
+    "_org_to_dict",
+    "_run_org",
+    "_run_remediate",
+    "_run_repo",
+    "_safe_component",
+    "_table_to_dict",
+    "_version_callback",
+    "app",
+    "main",
+    "remediate",
+    "repo_outputs",
+    "report",
+    "write_org_files",
+]

github_security_report-0.11.0/src/github_security_report/cli/__main__.py

@@ -0,0 +1,16 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 The Linux Foundation
+"""Support ``python -m github_security_report.cli``.
+
+The console script declared in ``pyproject.toml`` is the usual entry point, but
+the module form worked while the CLI was a single module and is preserved here:
+a package cannot be executed through the ``if __name__ == "__main__"`` guard in
+its ``__init__``, so it needs this file instead.
+"""
+
+from __future__ import annotations
+
+from github_security_report.cli.app import app
+
+if __name__ == "__main__":  # pragma: no cover
+    app()