{"id":43856262,"url":"https://github.com/ivuorinen/gh-codeql-report","last_synced_at":"2026-02-06T09:22:19.965Z","repository":{"id":317419008,"uuid":"1067385920","full_name":"ivuorinen/gh-codeql-report","owner":"ivuorinen","description":"Collect repository CodeQL findings as a LLM-friendly report for easier fixing.","archived":false,"fork":false,"pushed_at":"2026-02-02T20:50:09.000Z","size":86,"stargazers_count":0,"open_issues_count":9,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-03T10:44:29.654Z","etag":null,"topics":["cli","codeql","llm","tool","ts"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ivuorinen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-30T19:32:06.000Z","updated_at":"2026-01-24T00:50:39.000Z","dependencies_parsed_at":"2025-10-07T16:00:51.903Z","dependency_job_id":null,"html_url":"https://github.com/ivuorinen/gh-codeql-report","commit_stats":null,"previous_names":["ivuorinen/gh-codeql-report"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/ivuorinen/gh-codeql-report","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivuorinen%2Fgh-codeql-report","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivuorinen%2Fgh-codeql-report/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivuorinen%2Fgh-codeql-report/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivuorinen%2Fgh-codeql-report/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ivuorinen","download_url":"https://codeload.github.com/ivuorinen/gh-codeql-report/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivuorinen%2Fgh-codeql-report/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29156564,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-06T07:18:23.844Z","status":"ssl_error","status_checked_at":"2026-02-06T07:13:32.659Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","codeql","llm","tool","ts"],"created_at":"2026-02-06T09:22:19.147Z","updated_at":"2026-02-06T09:22:19.950Z","avatar_url":"https://github.com/ivuorinen.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gh-codeql-report\n\n[![CI](https://github.com/ivuorinen/gh-codeql-report/actions/workflows/ci.yml/badge.svg)](https://github.com/ivuorinen/gh-codeql-report/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/@ivuorinen/gh-codeql-report.svg)](https://www.npmjs.com/package/@ivuorinen/gh-codeql-report)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n\u003e Collect repository CodeQL findings as a LLM-friendly report for easier fixing.\n\nA 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.\n\n## Features\n\n- 🔍 **Automatic Repository Detection** - Detects GitHub repository from local git remotes\n- 🔐 **Multiple Authentication Methods** - Uses `GITHUB_TOKEN` environment variable or GitHub CLI (`gh`)\n- 📊 **Multiple Output Formats** - JSON, SARIF, Markdown, and Plain Text\n- 🎚️ **Configurable Detail Levels** - Choose from minimum, medium, full, or raw detail\n- 🎉 **Clean Exit for No Alerts** - Celebrates when no security issues are found\n- 📝 **Comprehensive Reports** - Includes rule details, locations, messages, and metadata\n- 🚀 **Easy Integration** - Use with `npx` or install globally\n\n## Installation\n\n### Using npx (Recommended)\n\nNo installation required:\n\n```bash\nnpx @ivuorinen/gh-codeql-report\n```\n\n### Global Installation\n\n```bash\nnpm install -g @ivuorinen/gh-codeql-report\ngh-codeql-report\n```\n\n### Local Development\n\n```bash\ngit clone https://github.com/ivuorinen/gh-codeql-report.git\ncd gh-codeql-report\nnpm install\nnpm run build\n```\n\n## Prerequisites\n\n- **Node.js** 18+ (ES Modules support)\n- **GitHub repository** with CodeQL scanning enabled\n- **Authentication**: Either:\n  - `GITHUB_TOKEN` environment variable with `security_events:read` scope, or\n  - GitHub CLI (`gh`) authenticated\n\n## Authentication\n\n### Option 1: Environment Variable\n\n```bash\nexport GITHUB_TOKEN=\"ghp_your_token_here\"\nnpx @ivuorinen/gh-codeql-report\n```\n\n### Option 2: GitHub CLI\n\n```bash\ngh auth login\nnpx @ivuorinen/gh-codeql-report\n```\n\nThe tool will automatically use `gh` CLI if `GITHUB_TOKEN` is not set.\n\n## Usage\n\n### Basic Usage\n\nRun in your repository directory:\n\n```bash\nnpx @ivuorinen/gh-codeql-report\n```\n\nThis will:\n1. Detect the repository from your git remote\n2. Fetch all open CodeQL alerts\n3. Generate a `code-scanning-report-[timestamp].json` file with medium detail\n\n### CLI Options\n\n```bash\ngh-codeql-report [options]\n```\n\n| Option      | Alias | Description                                      | Default                                     |\n|-------------|-------|--------------------------------------------------|---------------------------------------------|\n| `--format`  | `-f`  | Output format: `json`, `sarif`, `txt`, `md`      | `json`                                      |\n| `--detail`  | `-d`  | Detail level: `minimum`, `medium`, `full`, `raw` | `medium`                                    |\n| `--output`  | `-o`  | Output file path                                 | `code-scanning-report-[timestamp].[format]` |\n| `--help`    | `-h`  | Show help                                        |                                             |\n| `--version` | `-v`  | Show version                                     |                                             |\n\n### Examples\n\n#### Generate JSON Report with Full Detail\n\n```bash\nnpx @ivuorinen/gh-codeql-report --format json --detail full\n```\n\n#### Generate Markdown Report for LLM\n\n```bash\nnpx @ivuorinen/gh-codeql-report --format md --output security-report.md\n```\n\n#### Generate SARIF Report\n\n```bash\nnpx @ivuorinen/gh-codeql-report --format sarif --output results.sarif\n```\n\n#### Get Raw API Response\n\n```bash\nnpx @ivuorinen/gh-codeql-report --detail raw --output raw-alerts.json\n```\n\n## Output Formats\n\n### JSON\nStructured JSON output with flattened alert data. Ideal for programmatic processing and LLM consumption.\n\n### SARIF\nStandard SARIF v2.1.0 format. Compatible with many security tools and CI/CD platforms.\n\n### Markdown\nHuman-readable markdown with tables and sections. Great for documentation and LLM context.\n\n### Text\nPlain text format for quick reading and terminal output.\n\n## Detail Levels\n\n### Minimum\nEssential information only:\n- Alert number and rule ID/name\n- Severity and message\n- File path and line numbers\n- Commit SHA\n\n### Medium (Default)\nBalanced detail for most use cases:\n- Everything from minimum level\n- Rule description\n- Column numbers\n- Alert state (open, dismissed, etc.)\n\n### Full\nComplete information:\n- Everything from medium level\n- Git reference (branch/tag)\n- Analysis key and category\n- Tool name and version\n- Help text (if available)\n\n### Raw\nOriginal API response without processing. Useful for debugging or custom processing.\n\n## Exit Codes\n\n- `0` - Success (report generated or no alerts found)\n- `1` - Error (authentication failed, repository not found, API error, etc.)\n\n## Development\n\n### Setup\n\n```bash\nnpm install\n```\n\n### Build\n\n```bash\nnpm run build\n```\n\nCompiles TypeScript to `dist/` directory.\n\n### Run Locally\n\n```bash\n# Using ts-node\nnpx tsx src/cli.ts\n\n# Using compiled version\nnode dist/cli.js\n```\n\n### Code Quality\n\n```bash\n# Lint with Biome\nnpm run lint\n\n# Lint with auto-fix\nnpm run lint:fix\n\n# Format code\nnpm run format\n```\n\n### Testing\n\n```bash\n# Run all tests with coverage\nnpm test\n\n# Current coverage: 98.91%\n```\n\nThe test suite includes:\n- Unit tests for all formatters\n- Integration tests for CLI\n- Error handling scenarios\n- GitHub API mocking\n\n## Project Structure\n\n```\nsrc/\n├── cli.ts              # Main CLI entry point\n├── formatters/         # Output format generators\n│   ├── json.ts\n│   ├── sarif.ts\n│   ├── markdown.ts\n│   └── text.ts\n├── lib/                # Core functionality\n│   ├── auth.ts         # GitHub authentication\n│   ├── codeql.ts       # CodeQL API client\n│   ├── git.ts          # Git remote parsing\n│   └── types.ts        # TypeScript types\n└── __tests__/          # Test suites\n```\n\n## CI/CD\n\nThe project uses GitHub Actions for:\n- **CI**: Linting, testing, and building on every push/PR\n- **Release**: Automated npm publishing on version tags\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Run tests (`npm test`)\n5. Run linting (`npm run lint:fix`)\n6. Commit your changes (`git commit -m 'Add amazing feature'`)\n7. Push to the branch (`git push origin feature/amazing-feature`)\n8. Open a Pull Request\n\n### Code Style\n\n- ES Modules (type: module)\n- TypeScript with strict mode\n- Biome for linting and formatting\n- 2-space indentation\n- LF line endings\n\n## Use Cases\n\n### For LLMs\nFeed the generated reports to AI assistants for:\n- Security vulnerability analysis\n- Remediation suggestions\n- Code review assistance\n- Documentation generation\n\n### For CI/CD\nIntegrate into pipelines for:\n- Security gate checks\n- Automated reporting\n- Trend analysis\n- Alert notifications\n\n### For Security Teams\n- Centralized alert collection\n- Custom report formatting\n- Historical data export\n- Integration with ticketing systems\n\n## Troubleshooting\n\n### No git remotes found\nEnsure you're in a git repository with a GitHub remote:\n```bash\ngit remote -v\n```\n\n### Authentication failed\nCheck your token or GitHub CLI:\n```bash\necho $GITHUB_TOKEN\n# or\ngh auth status\n```\n\n### No CodeQL alerts found\nThis is good news! It means your repository has no open security issues.\n\n## License\n\n[MIT](LICENSE) © 2025 Ismo Vuorinen\n\n## Links\n\n- [GitHub Repository](https://github.com/ivuorinen/gh-codeql-report)\n- [npm Package](https://www.npmjs.com/package/@ivuorinen/gh-codeql-report)\n- [Issue Tracker](https://github.com/ivuorinen/gh-codeql-report/issues)\n- [CodeQL Documentation](https://docs.github.com/en/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fivuorinen%2Fgh-codeql-report","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fivuorinen%2Fgh-codeql-report","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fivuorinen%2Fgh-codeql-report/lists"}