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

$3

No installation required:

``bash
npx @ivuorinen/gh-codeql-report
`

$3

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

$3

`bash
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

$3

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

$3

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

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

Usage

$3

Run in your repository directory:

`bash
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

$3

`bash
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 | |

$3

#### Generate JSON Report with Full Detail

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

#### Generate Markdown Report for LLM

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

#### Generate SARIF Report

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

#### Get Raw API Response

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

Output Formats

$3

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

$3

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

$3

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

$3

Plain text format for quick reading and terminal output.

Detail Levels

$3

Essential information only:
- Alert number and rule ID/name
- Severity and message
- File path and line numbers
- Commit SHA

$3

Balanced detail for most use cases:
- Everything from minimum level
- Rule description
- Column numbers
- Alert state (open, dismissed, etc.)

$3

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

$3

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

$3

`bash
npm install
`

$3

`bash
npm run build
`

Compiles TypeScript to dist/ directory.

$3

`bash


Using ts-node

npx tsx src/cli.ts

Using compiled version

node dist/cli.js
`

$3

`bash


Lint with Biome

npm run lint

Lint with auto-fix

npm run lint:fix

Format code

npm run format
`

$3

`bash


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

$3

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

Use Cases

$3

Feed the generated reports to AI assistants for:
- Security vulnerability analysis
- Remediation suggestions
- Code review assistance
- Documentation generation

$3

Integrate into pipelines for:
- Security gate checks
- Automated reporting
- Trend analysis
- Alert notifications

$3

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

Troubleshooting

$3

Ensure you're in a git repository with a GitHub remote:
`bash
git remote -v
`

$3

Check your token or GitHub CLI:
`bash
echo $GITHUB_TOKEN

or

gh auth status
``

$3

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