How sharmajidotdev/netra works
Project type and purpose
• Netra is an open-source, Go-based CLI tool for scanning code repos for hard-coded secrets (API keys, tokens, credentials). It’s designed both for interactive use (local scans) and automated CI/CD integration (GitHub Actions, Docker, etc.).
File structure
• cmd/netra: the CLI entry point (main.go).
• internal/cli: argument parsing and CLI orchestration.
• internal/config: loading .netra.yaml and ignore rules.
• internal/scanner: core engine that walks file trees or diffs.
• internal/detect: detectors (regex + entropy + utils).
• internal/llm: optional LLM-based filtering and explanations.
• internal/git: diff parsing support.
• internal/output: formatters (human, JSON, SARIF).
• internal/rules: built-in regex rule definitions.
• pkg/types: common data structures (findings, secrets, metadata).
• build/: Dockerfiles, GitHub Action, goreleaser config.
• test/: fixtures and unit tests.
README for architectural cues
• Three detection techniques: regex patterns, entropy checks, LLM filtering.
• Multiple output formats.
• CI exit codes (0/1/2) to drive automation.
• GitHub Action wrapper for PR scanning.
• Configurable via .netra.yaml and .secretsignore.
• CLI Interface (cmd/netra & internal/cli)
• Config Loader (internal/config)
• Scanner Engine (internal/scanner)
• Detector Subsystem
– Regex Detector (internal/detect/regex.go + rules)
– Entropy Detector (internal/detect/entropy.go)
• LLM Filter & Explainer (internal/llm) [optional]
• Git Diff Handler (internal/git)
• Output Formatters (internal/output: human, JSON, SARIF)
• Shared Data Models (pkg/types)
• External Services
– File System / Git Repo
– LLM API (OpenAI or local)
• CI/CD Integration
– GitHub Action (build/action)
– Docker image (build/Dockerfile)
1. User invokes netra CLI → CLI Interface.
2. CLI reads flags → Config Loader → loads rules & ignores.
3. Scanner Engine ← Config; chooses file traversal or diff mode (via Git Diff Handler).
4. For each file or changed line: send content to Detector Subsystem.
5. Regex & Entropy Detectors emit raw findings.
6. (Optional) pass raw findings to LLM Filter → refine results + explanations.
7. Aggregate findings → Output Formatters based on chosen format.
8. Formatter prints to stdout or writes SARIF/JSON.
9. CLI exits with code 0/1/2.
10. GitHub Action workflow runs CLI inside a Docker container.
c. Architectural patterns & design principles
• Layered, modular design: separation between CLI, config, scanning, detection, and output.
• Plugin-style detectors: easy to add new regex or entropy rules.
• Optional LLM integration isolated behind an interface.
• Single-binary distribution for simplicity.
• CI/CD as a consumer of the CLI, not part of the binary itself.
d. Key technologies & frameworks
• Go modules for dependency management (go.mod)
• YAML parsing for config
• Regular expressions & entropy calculations
• OpenAI API (or pluggable LLM)
• JSON & SARIF output
• Docker & GitHub Actions for packaging & CI
Detail without overcomplicating
• Every module listed in the file tree as a node or sub-node.
• Extension points (where new detectors or outputs would hook in).