gh-codeql-report

Collect repository CodeQL findings as a LLM-friendly report for easier fixing.

A TypeScript CLI tool that fetches CodeQL security scanning results from GitHub repositories and formats them into LLM-friendly reports. Perfect for feeding security alerts to AI assistants for analysis and remediation suggestions.

Features

• 🔍 Automatic Repository Detection - Detects GitHub repository from local git remotes
• 🔐 Multiple Authentication Methods - Uses GITHUB_TOKEN environment variable or GitHub CLI (gh)
• 📊 Multiple Output Formats - JSON, SARIF, Markdown, and Plain Text
• 🎚️ Configurable Detail Levels - Choose from minimum, medium, full, or raw detail
• 🎉 Clean Exit for No Alerts - Celebrates when no security issues are found
• 📝 Comprehensive Reports - Includes rule details, locations, messages, and metadata
• 🚀 Easy Integration - Use with npx or install globally

Installation

Using npx (Recommended)

No installation required:

npx @ivuorinen/gh-codeql-report

Global Installation

npm install -g @ivuorinen/gh-codeql-report
gh-codeql-report

Local Development

git clone https://github.com/ivuorinen/gh-codeql-report.git
cd gh-codeql-report
npm install
npm run build

Prerequisites

• Node.js 18+ (ES Modules support)
• GitHub repository with CodeQL scanning enabled
• Authentication: Either:
  • GITHUB_TOKEN environment variable with security_events:read scope, or
  • GitHub CLI (gh) authenticated

Authentication

Option 1: Environment Variable

export GITHUB_TOKEN="ghp_your_token_here"
npx @ivuorinen/gh-codeql-report

Option 2: GitHub CLI

gh auth login
npx @ivuorinen/gh-codeql-report

The tool will automatically use gh CLI if GITHUB_TOKEN is not set.

Usage

Basic Usage

Run in your repository directory:

npx @ivuorinen/gh-codeql-report

This will:

1. Detect the repository from your git remote
2. Fetch all open CodeQL alerts
3. Generate a code-scanning-report-[timestamp].json file with medium detail

CLI Options

gh-codeql-report [options]

| Option | Alias | Description | Default | |-------------|-------|--------------------------------------------------|---------------------------------------------| | --format | -f | Output format: json, sarif, txt, md | json | | --detail | -d | Detail level: minimum, medium, full, raw | medium | | --output | -o | Output file path | code-scanning-report-[timestamp].[format] | | --help | -h | Show help | | | --version | -v | Show version | |

Examples

Generate JSON Report with Full Detail

npx @ivuorinen/gh-codeql-report --format json --detail full

Generate Markdown Report for LLM

npx @ivuorinen/gh-codeql-report --format md --output security-report.md

Generate SARIF Report

npx @ivuorinen/gh-codeql-report --format sarif --output results.sarif

Get Raw API Response

npx @ivuorinen/gh-codeql-report --detail raw --output raw-alerts.json

Output Formats

JSON

Structured JSON output with flattened alert data. Ideal for programmatic processing and LLM consumption.

SARIF

Standard SARIF v2.1.0 format. Compatible with many security tools and CI/CD platforms.

Markdown

Human-readable markdown with tables and sections. Great for documentation and LLM context.

Text

Plain text format for quick reading and terminal output.

Detail Levels

Minimum

Essential information only:

• Alert number and rule ID/name
• Severity and message
• File path and line numbers
• Commit SHA

Medium (Default)

Balanced detail for most use cases:

• Everything from minimum level
• Rule description
• Column numbers
• Alert state (open, dismissed, etc.)

Full

Complete information:

• Everything from medium level
• Git reference (branch/tag)
• Analysis key and category
• Tool name and version
• Help text (if available)

Raw

Original API response without processing. Useful for debugging or custom processing.

Exit Codes

• 0 - Success (report generated or no alerts found)
• 1 - Error (authentication failed, repository not found, API error, etc.)

Development

Setup

npm install

Build

npm run build

Compiles TypeScript to dist/ directory.

Run Locally

# Using ts-node
npx tsx src/cli.ts

# Using compiled version
node dist/cli.js

Code Quality

# Lint with Biome
npm run lint

# Lint with auto-fix
npm run lint:fix

# Format code
npm run format

Testing

# Run all tests with coverage
npm test

# Current coverage: 98.91%

The test suite includes:

• Unit tests for all formatters
• Integration tests for CLI
• Error handling scenarios
• GitHub API mocking

Project Structure

src/
├── cli.ts              # Main CLI entry point
├── formatters/         # Output format generators
│   ├── json.ts
│   ├── sarif.ts
│   ├── markdown.ts
│   └── text.ts
├── lib/                # Core functionality
│   ├── auth.ts         # GitHub authentication
│   ├── codeql.ts       # CodeQL API client
│   ├── git.ts          # Git remote parsing
│   └── types.ts        # TypeScript types
└── __tests__/          # Test suites

CI/CD

The project uses GitHub Actions for:

• CI: Linting, testing, and building on every push/PR
• Release: Automated npm publishing on version tags

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (npm test)
5. Run linting (npm run lint:fix)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Code Style

• ES Modules (type: module)
• TypeScript with strict mode
• Biome for linting and formatting
• 2-space indentation
• LF line endings

Use Cases

For LLMs

Feed the generated reports to AI assistants for:

• Security vulnerability analysis
• Remediation suggestions
• Code review assistance
• Documentation generation

For CI/CD

Integrate into pipelines for:

• Security gate checks
• Automated reporting
• Trend analysis
• Alert notifications

For Security Teams

• Centralized alert collection
• Custom report formatting
• Historical data export
• Integration with ticketing systems

Troubleshooting

No git remotes found

Ensure you're in a git repository with a GitHub remote:

git remote -v

Authentication failed

Check your token or GitHub CLI:

echo $GITHUB_TOKEN
# or
gh auth status

No CodeQL alerts found

This is good news! It means your repository has no open security issues.

License

MIT © 2025 Ismo Vuorinen

Links

• GitHub Repository
• npm Package
• Issue Tracker
• CodeQL Documentation