github-manage-security-alerts-skill 1.0.0 → 1.0.1

package/SKILL.md

@@ -1,32 +1,32 @@
----
+---
 name: "github-manage-security-alerts"
 description: "Use when a user asks to inspect, triage, bulk-fix, bulk-dismiss, dismiss, reopen, resolve, assign, summarize, export, or configure GitHub repository security alerts across repositories, including code scanning, Dependabot, Dependabot malware, and secret scanning; securely reads the GitHub token from environment variables such as GITHUB_TOKEN"
 license: "Unlicense"
 metadata:
   short-description: "Inspect and triage GitHub security alerts"
 ---
-
-# GitHub Security Alerts Management
-
-## Overview
-
-Use this skill when a user asks to inspect or manage GitHub repository security alerts, including:
-
-- code scanning alerts
-- Dependabot alerts
-- Dependabot malware alerts
-- secret scanning alerts
-- secret scanning alert locations
-- secret scanning scan history
-- repository security settings overview
-- raw GitHub security API inspection across repositories
-- bulk alert export for offline triage or reporting workflows
-- bulk alert mutation for high-volume cleanup workflows
-
-The bundled helper is repository-agnostic:
-
-- point `--repo` at any local checkout
-- let it auto-detect `owner/repo` and the GitHub host from the git remote
+
+# GitHub Security Alerts Management
+
+## Overview
+
+Use this skill when a user asks to inspect or manage GitHub repository security alerts, including:
+
+- code scanning alerts
+- Dependabot alerts
+- Dependabot malware alerts
+- secret scanning alerts
+- secret scanning alert locations
+- secret scanning scan history
+- repository security settings overview
+- raw GitHub security API inspection across repositories
+- bulk alert export for offline triage or reporting workflows
+- bulk alert mutation for high-volume cleanup workflows
+
+The bundled helper is repository-agnostic:
+
+- point `--repo` at any local checkout
+- let it auto-detect `owner/repo` and the GitHub host from the git remote
 - or pass `--repository owner/repo` explicitly
 - authenticate via environment variable instead of putting a token on the command line
 - optionally override the API base URL for custom environments
@@ -42,213 +42,213 @@ Supports GitHub.com and standard GHES API base URL derivation from git remotes,
 Use `repo` when the target is a local checkout, defaulting to `.`.
 Use optional `repository` and `token_env` values when auto-detection is not enough.
 Common commands include `summary`, `export-alerts`, `bulk-update-alerts`, `repo-security-overview`, `list-code-scanning`, `show-code-scanning`, `update-code-scanning`, `list-dependabot`, `show-dependabot`, `update-dependabot`, `list-malware`, `show-malware`, `update-malware`, `list-secret-scanning`, `show-secret-scanning`, `update-secret-scanning`, `list-secret-locations`, `secret-scan-history`, and `api-call`.
-
-## Security model
-
-Do not paste GitHub tokens into command arguments.
-
-Preferred pattern:
-
-```powershell
-$env:GITHUB_TOKEN = Get-Secret GITHUB_TOKEN -AsPlainText
-```
-
-If a repository uses a different environment variable name, either export that variable first or pass the variable name with `--token-env`.
-
-Examples:
-
-```powershell
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" summary --repo "."
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" summary --repo "." --token-env GITHUB_TOKEN
-```
-
-## Inputs
-
-- `repo`: path inside the target repository checkout (default `.`)
-- `repository`: optional explicit `owner/repo` override
-- `api_base_url`: optional explicit API base URL override
-- `token_env`: optional environment variable name containing the token; repeatable for fallbacks
-- `json`: optional machine-readable output flag
-
-## Important note about malware alerts
-
-GitHub surfaces malware findings as **Dependabot malware alerts**.
-
-There is not a separate repository alert family with its own dedicated REST surface. The bundled helper therefore treats malware as a filtered subset of Dependabot alerts and cross-references each alert's advisory GHSA against the GitHub Advisory Database to identify advisories whose type is `malware`.
-
-That means:
-
-- `list-malware`, `show-malware`, and `update-malware` are backed by Dependabot alert APIs
-- malware classification is strongest on GitHub.com, where the advisory database endpoint is available
-- if advisory type lookup is unavailable on the target host, the helper reports that clearly instead of silently guessing
-
-## Quick start
-
-### 1. Inspect the current security state
-
-```powershell
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" summary --repo "."
-```
-
-### 2. View repository security settings overview
-
-```powershell
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" repo-security-overview --repo "."
-```
-
-### 2.5 Export the full alert sets for bulk triage
-
-```powershell
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" export-alerts --repo "." --json
-```
-
-### 3. List code scanning alerts
-
-```powershell
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-code-scanning --repo "." --state open --severity high,error
-```
-
-### 3.5 Bulk-dismiss or bulk-reopen alerts
-
-```powershell
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" bulk-update-alerts --repo "." --surface code-scanning --select-state open --target-state dismissed --dismissed-reason "false positive" --comment "Reviewed and intentionally dismissed." --limit 10 --dry-run --json
-
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" bulk-update-alerts --repo "." --surface dependabot --select-state open --target-state dismissed --dismissed-reason tolerable_risk --comment "Accepted until the next dependency refresh." --limit 25 --dry-run --json
-
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" bulk-update-alerts --repo "." --surface secret-scanning --select-state open --target-state resolved --resolution used_in_tests --limit 25 --dry-run --json
-```
-
-### 4. Dismiss or reopen a code scanning alert
-
-```powershell
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-code-scanning --repo "." --alert 42 --state dismissed --dismissed-reason false_positive --comment "False positive after manual review." --dry-run
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-code-scanning --repo "." --alert 42 --state open
-```
-
-### 5. List Dependabot alerts
-
-```powershell
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-dependabot --repo "." --state open --ecosystem npm --has patch
-```
-
-### 6. Dismiss or reopen a Dependabot alert
-
-```powershell
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-dependabot --repo "." --alert 7 --state dismissed --dismissed-reason tolerable_risk --comment "Accepted until next quarterly upgrade." --dry-run
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-dependabot --repo "." --alert 7 --state open
-```
-
-### 7. List malware alerts
-
-```powershell
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-malware --repo "." --state open
-```
-
-### 8. List secret scanning alerts safely
-
-```powershell
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-secret-scanning --repo "." --state open
-```
-
-Secret values are hidden by default.
-
-### 9. Resolve or reopen a secret scanning alert
-
-```powershell
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-secret-scanning --repo "." --alert 11 --state resolved --resolution revoked --comment "Token revoked and rotated." --dry-run
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-secret-scanning --repo "." --alert 11 --state open
-```
-
-### 10. Show secret locations and scan history
-
-```powershell
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-secret-locations --repo "." --alert 11
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" secret-scan-history --repo "."
-```
-
-### 11. Use the raw API fallback for anything not wrapped yet
-
-```powershell
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" api-call --repo "." --endpoint /repos/OWNER/REPO/code-scanning/default-setup
-```
-
-## Workflow
-
-1. Resolve authentication securely.
-   - Prefer an environment variable like `GITHUB_TOKEN`.
-   - If needed, load it from a secret manager into an environment variable first.
-   - Never print the token in logs or chat output.
-2. Resolve the target repository.
-   - Prefer `--repo` and auto-detection from git remote.
-   - Fall back to `--repository owner/repo` when the local checkout is unavailable or nonstandard.
-3. Inspect current findings.
-   - Run `summary` first.
-   - Use `export-alerts` when you need a fuller multi-surface JSON snapshot for bulk triage or external reporting.
-   - Use the list/show commands for the alert family you care about.
-   - Use `repo-security-overview` when the question is about enablement or available security settings.
-4. Classify findings.
-   - Fix real defects in code or dependency configuration when appropriate.
-   - Dismiss only when you have a clear justification.
-   - Reopen alerts when the earlier dismissal or resolution is no longer valid.
-   - Use `bulk-update-alerts` when a repository has dozens or hundreds of obviously mis-triaged alerts that need the same action.
-5. Apply mutations carefully.
-   - Prefer `--dry-run` first for risky changes.
-   - Add a short, actionable dismissal or resolution comment.
-   - Remember that write operations need the corresponding GitHub permissions.
-6. Verify the post-change state.
-   - Re-run the relevant list/show command.
-   - For code or dependency fixes, wait for the next GitHub analysis cycle if you expect the alert to disappear naturally.
-
-## Bundled resources
-
-### scripts/manage_github_security_alerts.py
-
-Repository-agnostic helper for GitHub repository security alerts.
-
-Supported commands:
-
-- `summary`
-- `export-alerts`
-- `bulk-update-alerts`
-- `repo-security-overview`
-- `list-code-scanning`
-- `show-code-scanning`
-- `update-code-scanning`
-- `list-dependabot`
-- `show-dependabot`
-- `update-dependabot`
-- `list-malware`
-- `show-malware`
-- `update-malware`
-- `list-secret-scanning`
-- `show-secret-scanning`
-- `update-secret-scanning`
-- `list-secret-locations`
-- `secret-scan-history`
-- `api-call`
-
-Implementation modules:
-
-- `github_security_api.py`
-- `github_security_cli.py`
-- `github_security_common.py`
-- `github_security_operations.py`
-- `github_security_render.py`
-
-Examples:
-
-```powershell
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" summary --repo "." --json
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" export-alerts --repo "." --json
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" bulk-update-alerts --repo "." --surface code-scanning --select-state open --target-state dismissed --dismissed-reason "false positive" --comment "Reviewed and intentionally dismissed." --limit 10 --dry-run --json
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-code-scanning --repo "." --state open --per-page 100 --json
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-code-scanning --repo "." --alert 42 --state dismissed --dismissed-reason false_positive --comment "False positive after review." --dry-run
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-dependabot --repo "." --state open --ecosystem npm --json
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-malware --repo "." --json
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-dependabot --repo "." --alert 7 --state dismissed --dismissed-reason tolerable_risk --comment "Accepted temporarily." --dry-run
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-secret-scanning --repo "." --state open --json
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-secret-scanning --repo "." --alert 11 --state resolved --resolution revoked --comment "Revoked and rotated." --dry-run
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-secret-locations --repo "." --alert 11 --json
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" secret-scan-history --repo "." --json
-python "<path-to-skill>/scripts/manage_github_security_alerts.py" api-call --repo "." --endpoint /repos/OWNER/REPO/dependabot/alerts --query-param state=open --json
-```
+
+## Security model
+
+Do not paste GitHub tokens into command arguments.
+
+Preferred pattern:
+
+```powershell
+$env:GITHUB_TOKEN = Get-Secret GITHUB_TOKEN -AsPlainText
+```
+
+If a repository uses a different environment variable name, either export that variable first or pass the variable name with `--token-env`.
+
+Examples:
+
+```powershell
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" summary --repo "."
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" summary --repo "." --token-env GITHUB_TOKEN
+```
+
+## Inputs
+
+- `repo`: path inside the target repository checkout (default `.`)
+- `repository`: optional explicit `owner/repo` override
+- `api_base_url`: optional explicit API base URL override
+- `token_env`: optional environment variable name containing the token; repeatable for fallbacks
+- `json`: optional machine-readable output flag
+
+## Important note about malware alerts
+
+GitHub surfaces malware findings as **Dependabot malware alerts**.
+
+There is not a separate repository alert family with its own dedicated REST surface. The bundled helper therefore treats malware as a filtered subset of Dependabot alerts and cross-references each alert's advisory GHSA against the GitHub Advisory Database to identify advisories whose type is `malware`.
+
+That means:
+
+- `list-malware`, `show-malware`, and `update-malware` are backed by Dependabot alert APIs
+- malware classification is strongest on GitHub.com, where the advisory database endpoint is available
+- if advisory type lookup is unavailable on the target host, the helper reports that clearly instead of silently guessing
+
+## Quick start
+
+### 1. Inspect the current security state
+
+```powershell
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" summary --repo "."
+```
+
+### 2. View repository security settings overview
+
+```powershell
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" repo-security-overview --repo "."
+```
+
+### 2.5 Export the full alert sets for bulk triage
+
+```powershell
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" export-alerts --repo "." --json
+```
+
+### 3. List code scanning alerts
+
+```powershell
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-code-scanning --repo "." --state open --severity high,error
+```
+
+### 3.5 Bulk-dismiss or bulk-reopen alerts
+
+```powershell
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" bulk-update-alerts --repo "." --surface code-scanning --select-state open --target-state dismissed --dismissed-reason "false positive" --comment "Reviewed and intentionally dismissed." --limit 10 --dry-run --json
+
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" bulk-update-alerts --repo "." --surface dependabot --select-state open --target-state dismissed --dismissed-reason tolerable_risk --comment "Accepted until the next dependency refresh." --limit 25 --dry-run --json
+
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" bulk-update-alerts --repo "." --surface secret-scanning --select-state open --target-state resolved --resolution used_in_tests --limit 25 --dry-run --json
+```
+
+### 4. Dismiss or reopen a code scanning alert
+
+```powershell
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-code-scanning --repo "." --alert 42 --state dismissed --dismissed-reason false_positive --comment "False positive after manual review." --dry-run
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-code-scanning --repo "." --alert 42 --state open
+```
+
+### 5. List Dependabot alerts
+
+```powershell
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-dependabot --repo "." --state open --ecosystem npm --has patch
+```
+
+### 6. Dismiss or reopen a Dependabot alert
+
+```powershell
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-dependabot --repo "." --alert 7 --state dismissed --dismissed-reason tolerable_risk --comment "Accepted until next quarterly upgrade." --dry-run
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-dependabot --repo "." --alert 7 --state open
+```
+
+### 7. List malware alerts
+
+```powershell
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-malware --repo "." --state open
+```
+
+### 8. List secret scanning alerts safely
+
+```powershell
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-secret-scanning --repo "." --state open
+```
+
+Secret values are hidden by default.
+
+### 9. Resolve or reopen a secret scanning alert
+
+```powershell
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-secret-scanning --repo "." --alert 11 --state resolved --resolution revoked --comment "Token revoked and rotated." --dry-run
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-secret-scanning --repo "." --alert 11 --state open
+```
+
+### 10. Show secret locations and scan history
+
+```powershell
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-secret-locations --repo "." --alert 11
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" secret-scan-history --repo "."
+```
+
+### 11. Use the raw API fallback for anything not wrapped yet
+
+```powershell
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" api-call --repo "." --endpoint /repos/OWNER/REPO/code-scanning/default-setup
+```
+
+## Workflow
+
+1. Resolve authentication securely.
+   - Prefer an environment variable like `GITHUB_TOKEN`.
+   - If needed, load it from a secret manager into an environment variable first.
+   - Never print the token in logs or chat output.
+2. Resolve the target repository.
+   - Prefer `--repo` and auto-detection from git remote.
+   - Fall back to `--repository owner/repo` when the local checkout is unavailable or nonstandard.
+3. Inspect current findings.
+   - Run `summary` first.
+   - Use `export-alerts` when you need a fuller multi-surface JSON snapshot for bulk triage or external reporting.
+   - Use the list/show commands for the alert family you care about.
+   - Use `repo-security-overview` when the question is about enablement or available security settings.
+4. Classify findings.
+   - Fix real defects in code or dependency configuration when appropriate.
+   - Dismiss only when you have a clear justification.
+   - Reopen alerts when the earlier dismissal or resolution is no longer valid.
+   - Use `bulk-update-alerts` when a repository has dozens or hundreds of obviously mis-triaged alerts that need the same action.
+5. Apply mutations carefully.
+   - Prefer `--dry-run` first for risky changes.
+   - Add a short, actionable dismissal or resolution comment.
+   - Remember that write operations need the corresponding GitHub permissions.
+6. Verify the post-change state.
+   - Re-run the relevant list/show command.
+   - For code or dependency fixes, wait for the next GitHub analysis cycle if you expect the alert to disappear naturally.
+
+## Bundled resources
+
+### scripts/manage_github_security_alerts.py
+
+Repository-agnostic helper for GitHub repository security alerts.
+
+Supported commands:
+
+- `summary`
+- `export-alerts`
+- `bulk-update-alerts`
+- `repo-security-overview`
+- `list-code-scanning`
+- `show-code-scanning`
+- `update-code-scanning`
+- `list-dependabot`
+- `show-dependabot`
+- `update-dependabot`
+- `list-malware`
+- `show-malware`
+- `update-malware`
+- `list-secret-scanning`
+- `show-secret-scanning`
+- `update-secret-scanning`
+- `list-secret-locations`
+- `secret-scan-history`
+- `api-call`
+
+Implementation modules:
+
+- `github_security_api.py`
+- `github_security_cli.py`
+- `github_security_common.py`
+- `github_security_operations.py`
+- `github_security_render.py`
+
+Examples:
+
+```powershell
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" summary --repo "." --json
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" export-alerts --repo "." --json
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" bulk-update-alerts --repo "." --surface code-scanning --select-state open --target-state dismissed --dismissed-reason "false positive" --comment "Reviewed and intentionally dismissed." --limit 10 --dry-run --json
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-code-scanning --repo "." --state open --per-page 100 --json
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-code-scanning --repo "." --alert 42 --state dismissed --dismissed-reason false_positive --comment "False positive after review." --dry-run
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-dependabot --repo "." --state open --ecosystem npm --json
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-malware --repo "." --json
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-dependabot --repo "." --alert 7 --state dismissed --dismissed-reason tolerable_risk --comment "Accepted temporarily." --dry-run
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-secret-scanning --repo "." --state open --json
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-secret-scanning --repo "." --alert 11 --state resolved --resolution revoked --comment "Revoked and rotated." --dry-run
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-secret-locations --repo "." --alert 11 --json
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" secret-scan-history --repo "." --json
+python "<path-to-skill>/scripts/manage_github_security_alerts.py" api-call --repo "." --endpoint /repos/OWNER/REPO/dependabot/alerts --query-param state=open --json
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "github-manage-security-alerts-skill",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "private": false,
   "description": "Codex skill for inspecting and triaging GitHub security alerts.",
   "license": "Unlicense",
@@ -39,9 +39,8 @@
   "scripts": {
     "validate": "node tools/validate-skill-package.mjs",
     "pack:dry-run": "npm pack --dry-run",
-    "publish:local": "npm run release:verify && npm publish",
-    "release:verify": "npm run validate && npm run pack:dry-run",
-    "stage:local": "npm run release:verify && npm stage publish"
+    "publish:local": "npm run release:verify && npm publish --access public",
+    "release:verify": "npm run validate && npm run pack:dry-run"
   },
   "codexSkill": {
     "name": "github-manage-security-alerts",