# sharmajidotdev/netra architecture

> Architecture diagram of the GitHub repository sharmajidotdev/netra, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sharmajidotdev/netra
- Repository: https://github.com/sharmajidotdev/netra

## Overview

##### 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).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User
    User["User"]:::external

    %% CLI Layer
    subgraph "CLI Layer"
        CLI["CLI Interface"]:::cli
        CLI_Orch["CLI Orchestration & Argument Parsing"]:::cli
    end

    %% Configuration
    Config["Config Loader"]:::adapter

    %% Scanner Engine
    subgraph "Scanner Engine"
        Scanner["Scanner Engine"]:::core
        File_Traversal["File Traversal"]:::core
        Git_Diff["Git Diff Handler"]:::core
    end

    %% Detector Subsystem
    subgraph "Detector Subsystem"
        Regex["Regex Detector"]:::core
        Entropy["Entropy Detector"]:::core
        Utils["Detector Utilities"]:::core
        Rules["Built-in Regex Rules"]:::core
    end

    %% Optional LLM
    LLM["LLM Filter & Explainer"]:::adapter

    %% Output Formatters
    subgraph "Output Formatters"
        Human["Human-Readable Formatter"]:::adapter
        JSON["JSON Formatter"]:::adapter
        SARIF["SARIF Formatter"]:::adapter
    end

    %% Shared Data Models
    Models["Shared Data Models"]:::core

    %% External Services
    subgraph "External Services"
        FS["File System / Git Repo"]:::extservices
        LLM_API["LLM API"]:::extservices
    end

    %% CI/CD Integration
    subgraph "CI/CD Integration"
        GH_Action["GitHub Action Wrapper"]:::ci
        Docker_CLI["Dockerfile for CLI Container"]:::ci
        Docker_Action["Dockerfile for GitHub Action"]:::ci
        GoReleaser["GoReleaser Config"]:::ci
        CI_CI["CI Workflow (ci.yml)"]:::ci
        CI_PR["PR Workflow (netra.yml)"]:::ci
        CI_Release["Release Workflow (release.yml)"]:::ci
    end

    %% Data Flow
    User -->|"invoke netra"| CLI
    CLI -->|"parse args"| CLI_Orch
    CLI_Orch -->|"load config"| Config
    Config -->|"rules & ignores"| Scanner
    Scanner -->|"walk files"| File_Traversal
    Scanner -->|"parse diffs"| Git_Diff
    File_Traversal -->|"file contents"| Regex
    File_Traversal -->|"file contents"| Entropy
    Git_Diff -->|"diff lines"| Regex
    Git_Diff -->|"diff lines"| Entropy
    Regex -->|"raw findings"| Models
    Entropy -->|"raw findings"| Models
    Utils -->|"helper functions"| Regex
    Utils -->|"helper functions"| Entropy
    Rules -->|"pattern defs"| Regex
    Models -->|"raw findings"| LLM
    LLM -->|"filtered findings"| Models
    Models -->|"aggregated findings"| Human
    Models -->|"aggregated findings"| JSON
    Models -->|"aggregated findings"| SARIF
    Human -->|"print report"| User
    JSON -->|"write JSON"| User
    SARIF -->|"write SARIF"| User
    Human -->|"exit code"| User
    JSON -->|"exit code"| User
    SARIF -->|"exit code"| User

    %% External Services Connections
    FS --> File_Traversal
    FS --> Git_Diff
    LLM_API --> LLM

    %% CI/CD Flow
    GH_Action -->|"runs in"| Docker_Action
    Docker_Action -->|"runs CLI in"| Docker_CLI
    Docker_CLI -->|"exec netra"| CLI
    GH_Action -->|"ci jobs"| CI_CI
    GH_Action -->|"pr jobs"| CI_PR
    GH_Action -->|"release jobs"| CI_Release

    %% Click Events
    click CLI "https://github.com/sharmajidotdev/netra/blob/main/cmd/netra/main.go"
    click CLI_Orch "https://github.com/sharmajidotdev/netra/blob/main/internal/cli/cli.go"
    click Config "https://github.com/sharmajidotdev/netra/blob/main/internal/config/config.go"
    click Scanner "https://github.com/sharmajidotdev/netra/blob/main/internal/scanner/scanner.go"
    click File_Traversal "https://github.com/sharmajidotdev/netra/blob/main/internal/scanner/walk.go"
    click Regex "https://github.com/sharmajidotdev/netra/blob/main/internal/detect/regex.go"
    click Entropy "https://github.com/sharmajidotdev/netra/blob/main/internal/detect/entropy.go"
    click Utils "https://github.com/sharmajidotdev/netra/blob/main/internal/detect/utils.go"
    click Rules "https://github.com/sharmajidotdev/netra/blob/main/internal/rules/rules.go"
    click LLM "https://github.com/sharmajidotdev/netra/blob/main/internal/llm/llm.go"
    click Git_Diff "https://github.com/sharmajidotdev/netra/blob/main/internal/git/diff.go"
    click Human "https://github.com/sharmajidotdev/netra/blob/main/internal/output/human.go"
    click JSON "https://github.com/sharmajidotdev/netra/blob/main/internal/output/json.go"
    click SARIF "https://github.com/sharmajidotdev/netra/blob/main/internal/output/sarif.go"
    click Models "https://github.com/sharmajidotdev/netra/blob/main/pkg/types/types.go"
    click Docker_CLI "https://github.com/sharmajidotdev/netra/tree/main/build/Dockerfile"
    click GH_Action "https://github.com/sharmajidotdev/netra/blob/main/build/action/action.yml"
    click Docker_Action "https://github.com/sharmajidotdev/netra/tree/main/build/action/Dockerfile"
    click GoReleaser "https://github.com/sharmajidotdev/netra/blob/main/build/goreleaser.yml"
    click CI_CI "https://github.com/sharmajidotdev/netra/blob/main/.github/workflows/ci.yml"
    click CI_PR "https://github.com/sharmajidotdev/netra/blob/main/.github/workflows/netra.yml"
    click CI_Release "https://github.com/sharmajidotdev/netra/blob/main/.github/workflows/release.yml"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366D6,color:#0366D6,stroke-width:1px;
    classDef adapter fill:#E8F5D0,stroke:#2E8B57,color:#2E8B57,stroke-width:1px;
    classDef external fill:#F0F0F0,stroke:#666666,color:#666666,stroke-width:1px,stroke-dasharray: 5 5;
    classDef extservices fill:#FFF2CC,stroke:#B8860B,color:#B8860B,stroke-width:1px;
    classDef cli fill:#FFE0E0,stroke:#D14343,color:#D14343,stroke-width:1px;
    classDef ci fill:#F5E6FF,stroke:#9C27B0,color:#9C27B0,stroke-width:1px;
```
