ghsec — GitHub Security Alerts CLI

A command-line tool that wraps the gh CLI to fetch, display, and manage GitHub security alerts (CodeQL/code scanning, Dependabot, secret scanning).

Prerequisites

• Python >= 3.10
• gh CLI installed and authenticated (gh auth login)
• uv for package management (recommended)

Installation

uv pip install .

Or for development:

uv sync

Usage

Run ghsec from inside a cloned GitHub repo (it auto-detects the repo from git remote), or specify --repo OWNER/REPO.

ghsec <subcommand> [options]

Global options:
  --repo OWNER/REPO    Override repo (default: auto-detect from git remote)
  --json               Output raw JSON instead of formatted tables

List alerts

# All security alert types
ghsec list

# Specific types
ghsec list-code          # Code scanning (CodeQL) only
ghsec list-deps          # Dependabot only
ghsec list-secrets       # Secret scanning only

# Filter by state or severity
ghsec list-code --state open --severity high

Show alert details

ghsec show code 1        # Code scanning alert #1
ghsec show dep 5         # Dependabot alert #5
ghsec show secret 3      # Secret scanning alert #3

Dismiss an alert

# Code scanning reasons: false_positive, wont_fix, used_in_tests
ghsec dismiss code 1 --reason wont_fix

# Dependabot reasons: fix_started, inaccurate, no_bandwidth, not_used, tolerable_risk
ghsec dismiss dep 5 --reason tolerable_risk --comment "low priority"

# Secret scanning reasons: false_positive, wont_fix, revoked, used_in_tests
ghsec dismiss secret 3 --reason revoked

Reopen a dismissed alert

ghsec reopen dep 5

JSON output

ghsec --json list-deps
ghsec --json show code 1

Running tests

bash test/run_tests.sh

Project structure

├── pyproject.toml          # Package metadata, dependencies, entry point
├── src/
│   └── ghsec/
│       ├── __init__.py     # Version string
│       ├── cli.py          # argparse setup, main entry point
│       ├── api.py          # gh api wrapper functions
│       └── display.py      # Rich table/detail formatting
└── test/
    ├── run_tests.sh        # Test runner script
    ├── fixtures.py         # Canned API responses
    ├── test_api.py         # API module tests
    ├── test_display.py     # Display formatting tests
    └── test_cli.py         # CLI argument & command handler tests

License

MIT