{"id":46937487,"url":"https://github.com/timoniersystems/lookout","last_synced_at":"2026-04-01T20:51:41.400Z","repository":{"id":343615053,"uuid":"1155071439","full_name":"timoniersystems/lookout","owner":"timoniersystems","description":"Vulnerability scanner and SBOM analyzer for software supply chain security. Processes CVE lists, Trivy scans, and CycloneDX/SPDX SBOMs with NVD enrichment, dependency graph analysis, and a web UI for interactive exploration.","archived":false,"fork":false,"pushed_at":"2026-03-21T03:05:23.000Z","size":14719,"stargazers_count":1,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-21T17:03:46.927Z","etag":null,"topics":["cve","cyclonedx","dgraph","docker","golang","helm","kubernetes","nvd","sbom","security","software-supply-chain","spdx","trivy","vulnerability-scanner"],"latest_commit_sha":null,"homepage":"","language":"Go","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/timoniersystems.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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":"2026-02-11T04:56:46.000Z","updated_at":"2026-03-21T03:05:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/timoniersystems/lookout","commit_stats":null,"previous_names":["timoniersystems/lookout"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/timoniersystems/lookout","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timoniersystems%2Flookout","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timoniersystems%2Flookout/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timoniersystems%2Flookout/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timoniersystems%2Flookout/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/timoniersystems","download_url":"https://codeload.github.com/timoniersystems/lookout/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timoniersystems%2Flookout/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291850,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: 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":["cve","cyclonedx","dgraph","docker","golang","helm","kubernetes","nvd","sbom","security","software-supply-chain","spdx","trivy","vulnerability-scanner"],"created_at":"2026-03-11T06:01:00.943Z","updated_at":"2026-04-01T20:51:41.392Z","avatar_url":"https://github.com/timoniersystems.png","language":"Go","readme":"# Lookout\n\n\u003e SBOM (CycloneDX \u0026 SPDX) and CVE vulnerability analysis tool with dependency path tracing\n\n[![CI](https://github.com/timoniersystems/lookout/actions/workflows/ci.yml/badge.svg)](https://github.com/timoniersystems/lookout/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## Demo\n\n\u003cdetails\u003e\n\u003csummary\u003e▶ Click to watch CLI demo\u003c/summary\u003e\n\n![Lookout demo](docs/demo.svg)\n\n\u003c/details\u003e\n\n## What is Lookout?\n\nLookout helps you understand and fix vulnerabilities in your software dependencies. It answers critical questions:\n\n- 📊 **What vulnerabilities exist in my software?**\n- 🔍 **How did this vulnerable package get into my project?**\n- 🛠️ **Which direct dependency should I upgrade to fix it?**\n\n### Key Features\n\n- **CVE Analysis** - Fetch detailed vulnerability data from the NVD with rate limiting and retry logic\n- **SBOM Scanning** - Scan Software Bill of Materials with Trivy integration\n- **Dependency Path Tracing** - Trace vulnerable transitive dependencies back to your root package\n- **Multi-Interface** - CLI for automation, Web UI with real-time progress tracking\n- **Graph Database** - Dgraph-powered dependency graph visualization\n- **Async Processing** - Background SBOM processing with SSE progress updates\n- **Severity Filtering** - Filter vulnerabilities by CRITICAL, HIGH, MEDIUM, LOW\n\n## Quick Start\n\n### CLI Usage\n\n```bash\n# Clone and build\ngit clone https://github.com/timoniersystems/lookout.git\ncd lookout\nmake build \u0026\u0026 make install\n\n# Fetch CVE data\nlookout cve CVE-2021-44228\n\n# Scan an SBOM\nlookout sbom examples/cyclonedx-sbom-example.json\n\n# Trace dependency path (requires Dgraph)\nmake up-standalone\nexport DGRAPH_HOST=localhost\nlookout sbom examples/cyclonedx-sbom-example.json \\\n  --dep-path 'pkg:composer/asm89/stack-cors@1.3.0'\n```\n\n### Web UI\n\n```bash\n# Generate TLS certificates\nmake certs\n\n# Start all services\nmake up\n\n# Access UI (HTTPS)\nopen https://localhost:7443\n\n# Access Dgraph Ratel\nopen http://localhost:8000\n```\n\n## Installation\n\n### Using Docker (Recommended)\n\n```bash\n# Generate TLS certificates\nmake certs\n\n# Start all services\nmake up\n```\n\nAccess points:\n- Lookout Web UI: https://localhost:7443 (HTTPS) or http://localhost:7080 (redirects to HTTPS)\n- Dgraph Ratel UI: http://localhost:8000\n- Dgraph API: http://localhost:8080\n\nSee [Docker Compose Guide](docs/DOCKER_COMPOSE.md) for detailed setup and configuration.\n\n### Binary Download\n\nDownload from [Releases](https://github.com/timoniersystems/lookout/releases):\n\n```bash\n# Linux\nwget https://github.com/timoniersystems/lookout/releases/latest/download/lookout-linux-amd64\nchmod +x lookout-linux-amd64\nsudo mv lookout-linux-amd64 /usr/local/bin/lookout\n\n# macOS (Apple Silicon)\nwget https://github.com/timoniersystems/lookout/releases/latest/download/lookout-darwin-arm64\nchmod +x lookout-darwin-arm64\nsudo mv lookout-darwin-arm64 /usr/local/bin/lookout\n\n# Verify\nlookout version\n```\n\n### Build from Source\n\n**Requirements:**\n- Go 1.26+\n- Docker \u0026 Docker Compose (for UI and dependency tracing)\n- Trivy (optional, for SBOM scanning)\n\n```bash\ngit clone https://github.com/timoniersystems/lookout.git\ncd lookout\nmake build\nmake install\n```\n\n## Documentation\n\n- 📖 **[Usage Guide](docs/USAGE.md)** - Complete guide with examples and workflows\n- 🐳 **[Docker Compose Guide](docs/DOCKER_COMPOSE.md)** - Running with Docker, services, ports, troubleshooting\n- ☸️ **[Kubernetes Deployment](docs/KUBERNETES_SETUP.md)** - Complete K8s guide: Kind cluster, Gateway API, ArgoCD GitOps, AWS ALB, production deployment\n- 🔒 **[TLS Setup Guide](docs/TLS_SETUP.md)** - HTTPS configuration and security best practices\n- 🏗️ **[Architecture](docs/ARCHITECTURE.md)** - System design and components\n- 💻 **[Contributing Guide](CONTRIBUTING.md)** - Development setup and contribution guide\n- 🚀 **[CI/CD Guide](docs/CI_CD.md)** - GitHub Actions workflows and releases\n\n## Example: Dependency Path Tracing\n\nWhen you find a vulnerability in a transitive dependency, Lookout shows you the path:\n\n```bash\nlookout sbom mybom.json --dep-path 'pkg:npm/minimist@1.2.5'\n```\n\nOutput:\n```\n════════════════════════════════════════════════════════════\n  DEPENDENCY PATH ANALYSIS\n════════════════════════════════════════════════════════════\n\n  Searched: pkg:npm/minimist@1.2.5\n  Depth:    3 level(s)\n\n  Dependency Tree:\n\n     🏠 pkg:npm/myapp@1.0.0\n     │\n     └──\u003e 📦 pkg:npm/mocha@8.4.0\n          │\n          └──\u003e 📦 pkg:npm/mkdirp@0.5.1\n               │\n               └──\u003e ⚠️  pkg:npm/minimist@1.2.5\n\n════════════════════════════════════════════════════════════\n\n  Legend:\n    🏠  = Root package (your application)\n    📦  = Intermediate dependency\n    ⚠️  = Vulnerable component\n```\n\n**Action:** Upgrade `mocha` to get the patched `minimist`.\n\n## Configuration\n\n### NVD API Key (Highly Recommended)\n\nGet 10x faster CVE lookups with an API key:\n\n```bash\n# Request key: https://nvd.nist.gov/developers/request-an-api-key\n\n# Set environment variable\nexport NVD_API_KEY=\"your-api-key-here\"\n\n# Add to shell profile for persistence\necho 'export NVD_API_KEY=\"your-api-key\"' \u003e\u003e ~/.zshrc\n```\n\n| Mode | Rate Limit | Speed |\n|------|-----------|-------|\n| Without API Key | 5 req/30s | 6s delay |\n| With API Key | 50 req/30s | 0.6s delay |\n\n### Environment Variables\n\n```bash\n# NVD API\nexport NVD_API_KEY=\"your-api-key\"\n\n# Dgraph connection (for CLI with Docker Dgraph)\nexport DGRAPH_HOST=localhost  # Use \"alpha\" when all in Docker\nexport DGRAPH_PORT=9080\n\n# Web server\nexport SERVER_PORT=3000\n```\n\nSee [Usage Guide](docs/USAGE.md#environment-variables) for all options.\n\n## Common Use Cases\n\n### 1. Security Audit\n\n```bash\n# Scan your SBOM for vulnerabilities\nlookout sbom path/to/sbom.json --severity high\n```\n\n### 2. Investigate Specific CVE\n\n```bash\n# Get detailed CVE information\nlookout cve CVE-2021-44228\n```\n\n### 3. Batch CVE Processing\n\n```bash\n# Process list of CVEs\ncat cves.txt\nCVE-2021-44228\nCVE-2022-23305\n\nlookout cve-file cves.txt\n```\n\n### 4. Fix Transitive Vulnerability\n\n```bash\n# 1. Scan and identify vulnerable package\nlookout sbom mybom.json\n\n# 2. Trace dependency path\nlookout sbom mybom.json --dep-path 'pkg:npm/lodash@4.17.20'\n\n# 3. Upgrade the direct dependency shown in path\n```\n\n## Project Structure\n\n```\nlookout/\n├── cmd/\n│   ├── cli/              # CLI application entry point (Cobra commands)\n│   └── ui/               # Web UI application entry point\n├── pkg/\n│   ├── cli/\n│   │   └── cli_processor/ # CVE formatting and output\n│   ├── common/\n│   │   ├── cyclonedx/    # CycloneDX SBOM parsing\n│   │   ├── spdx/         # SPDX SBOM parsing\n│   │   ├── fileutil/     # File utilities\n│   │   ├── handler/      # HTTP handlers\n│   │   ├── nvd/          # NVD API client\n│   │   ├── processor/    # File processing\n│   │   ├── progress/     # Progress tracking\n│   │   └── trivy/        # Trivy integration\n│   ├── config/           # Configuration management\n│   ├── graph/            # Graph operations and queries\n│   ├── interfaces/       # Interface definitions\n│   ├── logging/          # Structured logging\n│   ├── repository/       # Data access layer\n│   ├── service/          # Business logic layer\n│   ├── ui/               # UI components\n│   │   └── echo/         # Echo server setup\n│   └── validation/       # Input validation\n├── assets/\n│   ├── static/           # CSS, JavaScript\n│   └── templates/        # HTML templates\n├── nginx/                # Nginx reverse proxy config\n├── examples/             # Example SBOM files\n└── docs/                 # Documentation\n```\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for:\n- Development setup\n- Code style guidelines\n- Testing requirements\n- Submission process\n\n## Supported Formats\n\n- **SBOMs**: CycloneDX 1.4+ (JSON), SPDX 2.3+ (JSON)\n- **CVE Lists**: Plain text or Trivy JSON\n- **Package URLs**: [PURL Specification](https://github.com/package-url/purl-spec)\n\n## Requirements\n\n**For CLI:**\n- Go 1.26+ (build only)\n- Trivy (optional, for SBOM scanning)\n- Dgraph (optional, for dependency tracing)\n\n**For Web UI:**\n- Docker \u0026 Docker Compose\n\n## Known Limitations\n\n1. **Rate Limiting**: NVD API has strict rate limits. Use an API key for best performance.\n2. **SBOM Format**: Supports CycloneDX 1.4+ and SPDX 2.3+ (JSON only, XML not yet supported).\n3. **Large SBOMs**: Processing hundreds of CVEs can be slow. NVD API key highly recommended.\n\nSee [Usage Guide](docs/USAGE.md#troubleshooting) for solutions.\n\n## Verifying Releases\n\nAll release binaries and container images are signed with [SLSA build provenance](https://slsa.dev/) using GitHub's OIDC token. You can verify that an artifact was produced by this repository's CI and has not been tampered with.\n\n**Container image:**\n```bash\ngh attestation verify oci://ghcr.io/timoniersystems/lookout:latest --owner timoniersystems\n```\n\n**Release binary** (after downloading from the [releases page](https://github.com/timoniersystems/lookout/releases)):\n```bash\ngh attestation verify lookout-linux-amd64 --owner timoniersystems\n```\n\nRequires the [GitHub CLI](https://cli.github.com/) (`gh`).\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Acknowledgments\n\n- [National Vulnerability Database (NVD)](https://nvd.nist.gov/)\n- [Trivy](https://github.com/aquasecurity/trivy) - Vulnerability scanner\n- [Dgraph](https://dgraph.io/) - Graph database\n- [CycloneDX](https://cyclonedx.org/) - SBOM standard\n- [SPDX](https://spdx.dev/) - SBOM standard\n\n## Support\n\n- 📚 [Documentation](docs/)\n- 🐛 [Report Issues](https://github.com/timoniersystems/lookout/issues)\n- 💬 [Discussions](https://github.com/timoniersystems/lookout/discussions)\n\n---\n\n**Star ⭐ this repository if you find it useful!**\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimoniersystems%2Flookout","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimoniersystems%2Flookout","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimoniersystems%2Flookout/lists"}