Collect repository CodeQL findings as a LLM ready report for easier fixing.
npm install @ivuorinen/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.
- š 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
No installation required:
``bash`
npx @ivuorinen/gh-codeql-report
`bash`
npm install -g @ivuorinen/gh-codeql-report
gh-codeql-report
`bash`
git clone https://github.com/ivuorinen/gh-codeql-report.git
cd gh-codeql-report
npm install
npm run build
- Node.js 18+ (ES Modules support)
- GitHub repository with CodeQL scanning enabled
- Authentication: Either:
- GITHUB_TOKEN environment variable with security_events:read scope, orgh
- GitHub CLI () authenticated
`bash`
export GITHUB_TOKEN="ghp_your_token_here"
npx @ivuorinen/gh-codeql-report
`bash`
gh auth login
npx @ivuorinen/gh-codeql-report
The tool will automatically use gh CLI if GITHUB_TOKEN is not set.
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
`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 | |
#### 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
- 0 - Success (report generated or no alerts found)1
- - Error (authentication failed, repository not found, API error, etc.)
`bash`
npm install
`bash`
npm run build
Compiles TypeScript to dist/ directory.
`bashUsing ts-node
npx tsx src/cli.ts
$3
`bash
Lint with Biome
npm run lintLint with auto-fix
npm run lint:fixFormat code
npm run format
`$3
`bash
Run all tests with coverage
npm testCurrent 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 systemsTroubleshooting
$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
``MIT Ā© 2025 Ismo Vuorinen
- GitHub Repository
- npm Package
- Issue Tracker
- CodeQL Documentation