OpenSecAI

An end-to-end, AI-powered security scanner and auto-remediation platform. Run security agents locally, detect vulnerabilities, and self-heal breaking API changes automatically.

---

OpenSecAI orchestrates independent, local LangGraph agents managed via a modern Tauri-based desktop application. Run scans, interact with live logging, and review AI-driven patches without your source code or secrets ever leaving your machine.

• Local & secure. A Tauri desktop shell hosting a React frontend paired with a local FastAPI sidecar. No SaaS APIs, no external code uploads.
• Autonomous self-healing. Integrated LLM code-patching and Claude Code agents automatically remediate vulnerabilities, upgrade packages, and fix compilation errors.
• Human-in-the-loop (HITL). Uses LangGraph interrupts to pause, verify, and request decisions when build or analysis checks fail.
• Currently Go-first. Dependency scanning is currently supported for Go (Golang) projects, with support for more security domains (container scanning, SAST, secrets, IaC, SBOM, licensing) and programming languages planned for future releases.

Want a fully local, agentic security analysis pipeline running right on your workstation? You're in the right place.

---

🌟 Core Vision & Highlights

• Single-User Desktop First: Designed to run securely on a developer's local machine without exposing source code or secrets to external SaaS endpoints.
• Autonomous Agents: Built using LangGraph, agents scan target codebases, analyze results, and attempt self-healing/auto-remediation (using LLMs and Claude Code subprocesses) directly on the local filesystem.
• Human-in-the-Loop (HITL): Utilizes LangGraph interrupts to pause execution and request human guidance (e.g., when breaking changes are detected and code modification is needed).
• FastAPI Sidecar Backend: A Python-based FastAPI server runs as a local sidecar managed by the Tauri app, running on 127.0.0.1 and secured with token handshakes.
• SQLite Persistence: SQLModel-backed SQLite database tracks projects, execution jobs, live agent event logs, and historical findings.
• Typesafe Schema Codegen: Pydantic models automatically export to JSON Schemas, which are then compiled directly to TypeScript types for UI consumption.

---

📸 Screenshots

Landing Page	Agent Dashboard
Run Configuration	Live Job Logs & Progress
Human-in-the-Loop Decision	Historical Reports Browser

---

🏗️ System Architecture

OpenSecAI consists of three main components: the Rust-based Tauri container, the React-based frontend webview, and the Python-based API sidecar running LangGraph agents.

┌──────────────────────────────────────────────────────────────────────────────┐
│  Desktop App Container (Tauri Process)                                       │
│                                                                              │
│   ┌─────────────────┐    Tauri IPC    ┌──────────────────────────────┐       │
│   │  React + Vite   │ ◄────────────►  │  Rust Shell (src-tauri)      │       │
│   │  (Webview UI)   │   invoke / event│  • Window management         │       │
│   │  desktop/src    │                 │  • Sidecar supervisor        │       │
│   └────────┬────────┘                 │  • Process termination       │       │
│            │ HTTP + WS                │    (SIGKILL via active_pid)  │       │
│            │ (127.0.0.1:8765)         └────────────┬─────────────────┘       │
│            ▼                                       │                         │
│   ┌────────────────────────────────────────────────┼─────────────────────┐   │
│   │  Python Sidecar — FastAPI (opensecai.api)      │                     │   │
│   │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌───▼──────┐              │   │
│   │  │ Routes   │  │ WS App   │  │ Runtime  │  │ Storage  │              │   │
│   │  │ /agents  │  │ /ws/...  │  │ JobMgr   │  │ SQLite   │              │   │
│   │  │ /jobs    │  │ stream   │  │ EventBus │  │ stores   │              │   │
│   │  │ /projects│  │          │  │ registry │  │          │              │   │
│   │  │ /settings│  │          │  │          │  │          │              │   │
│   │  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘              │   │
│   │       │             │             │             │                    │   │
│   │       └─────────────┴──────┬──────┘             │                    │   │
│   │                            ▼                    ▼                    │   │
│   │                  ┌──────────────────┐   ┌──────────────────┐         │   │
│   │                  │  Agent Runners   │   │  opensecai.db    │         │   │
│   │                  │  (dep_scan, ...) │   │  (Jobs/Projects/ │         │   │
│   │                  │  LangGraph       │   │   Settings)      │         │   │
│   │                  └────────┬─────────┘   └──────────────────┘         │   │
│   │                           │                                          │   │
│   └───────────────────────────┼──────────────────────────────────────────┘   │
└───────────────────────────────┼──────────────────────────────────────────────┘
                                ▼
                  ┌──────────────────────────────────┐
                  │ Target Filesystem (Per Project)  │
                  │   <root_dir>/                    │
                  │     workspaces/<repo>/           │  ← Target repository source code
                  │     reports/<proj>/              │
                  │       <agent>/                   │
                  │         index.json               │  ← Run logs and history
                  │         index.json.lock          │  ← Cross-agent concurrent lock
                  │         <run_id>/                │
                  │           start.json             │  ← Pre-healing scan report
                  │           end.json               │  ← Post-healing scan report
                  │           diff.json              │  ← Fixed/persisted vulns diff
                  │           events.jsonl           │  ← Replayable log stream
                  │           active_pid             │  ← Process PID (for instant kill)
                  └──────────────────────────────────┘

---

🚀 Getting Started

Prerequisites

Make sure you have the following installed on your machine:

• Python: >= 3.13
• Rust: >= 1.77.2 (Tauri v2 requirement)
• Node.js: >= 20.0
• uv: Python package and project manager (recommended)
• Go (Golang): Required (the tool currently supports Go projects only)
• Trivy: Vulnerability scanner (required for dep_scan)

Setup Environment & Quick Start

Start by cloning the repository and entering the project directory:

git clone https://github.com/hitesharma/OpenSecAI
cd OpenSecAI

Next, choose one of the options below to install dependencies:

Option A: 🐧 Linux Quick Start (Automated Setup)

If you are running on a Debian/Ubuntu-based Linux environment, you can run our automated script to verify and install all system prerequisites, Node.js, Rust, Trivy, and uv, sync the Python virtual environment, and install the frontend packages:

make setup

Option B: 🛠️ Manual Setup (All Platforms)

To manually set up your environment:

1. Install Python dependencies:

   uv sync

2. Install frontend dependencies:

   cd desktop
   npm install
   cd ..

---

📂 Service Data Directory & Workspace Layout

OpenSecAI stores all analysis data locally. When you configure the application (via settings in the UI), you define a Service Data Directory (the global data root) which holds the workspaces and scan reports for all projects created within the app.

To prepare a repository for scanning:

1. Locate your configured Service Data Directory (in Dev/CLI mode, this defaults to the root of this cloned OpenSecAI repository).
2. Clone the target repository you want to scan directly inside the workspaces/ directory of your Service Data Directory:

   # Navigate to your Service Data Directory
   cd /path/to/your/service-data-dir
   
   # Clone the target repository into workspaces/
   mkdir -p workspaces
   cd workspaces
   git clone <your-target-repo-url>

3. In the Tauri GUI (or when setting the PROJECT environment variable on the CLI), specify the folder name of the cloned repository (e.g., your-target-repo) as the Workspace Name.

All scan results, events, and diff reports will be generated automatically in the reports/ directory adjacent to workspaces/ (categorized by project name).

---

💻 Running the App

Running the Tauri Desktop App (GUI)

To start the app in development mode (spawns both the Tauri desktop frame and the Python sidecar automatically):

make run-dev

Running the CLI Agent (Local Dev)

To run the default agent (dep_scan) directly on your CLI against a target workspace:

# Set target project and workspace name
export PROJECT=my-go-service
# Target workspace must exist under workspaces/my-go-service/ and contain a go.mod
make run

Running the API Sidecar Independently

If you want to debug FastAPI routes or test the API via tools like Swagger UI (http://localhost:8765/docs):

make api

---

🛠️ Development & Tooling

We use a central Makefile to consolidate standard development actions.

Command	Action
make install	Create virtual environment and sync python dependencies
make run	Run the dep_scan agent on CLI using main.py
make run-dev	Start Tauri GUI app in development mode
make api	Boot up the FastAPI sidecar server
make lint	Run Ruff linter checks
make format	Reformat python code using Ruff formatter
make typecheck	Run Pyright static type analysis
make codegen	Export Pydantic models to JSON schemas and compile to TypeScript interfaces
make clean	Clean up build artifacts and .venv

---

🤖 Adding a New Agent

Follow this recipe to add a new security domain agent:

1. Scaffold Directory: Create a subpackage inside opensecai/agents/:

   mkdir -p opensecai/agents/<agent_name>/prompts
   touch opensecai/agents/<agent_name>/{__init__,runner,graph,nodes,state}.py

2. Register Entrypoint: Register your agent's runner in pyproject.toml under [project.scripts]:

   opensecai-<agent_name> = "opensecai.agents.<agent_name>.runner:main"

3. Sync Environment: Run uv sync to update the script bindings in your environment.
4. Implement Graph & State:
   • Define the typed AgentState in state.py (with thread safety variables like log_fn and cancel_event).
   • Inherit the context and register nodes using LangGraph's StateGraph in graph.py / nodes.py. Ensure all paths are safely resolved via opensecai/core/paths.py.
   • Implement execution tracking using _run_tracked for any spawned subprocesses so they can be terminated properly.
5. Configure Human-in-the-Loop (HITL) Pauses (Optional): If your agent needs to pause and prompt the user for decisions:
   • Create contracts.py in your agent package and define/register a PauseContract with selection options:

     from opensecai.runtime.notification_contracts import register, PauseContract, PauseOption
     register(PauseContract(
         name="<agent_name>.some_decision",
         prompt="How should the agent proceed?",
         options=(
             PauseOption(value="go", label="Continue", desc="...", variant="primary"),
             PauseOption(value="stop", label="Abort", desc="...", variant="ghost"),
         ),
     ))

   • In your graph nodes, call interrupt({"contract": "<agent_name>.some_decision", "context": {...}}) to trigger the pause.
   • Import this contracts module inside your agent's registry runner in agent_registry.py (e.g. import opensecai.agents.<agent_name>.contracts) so the registration side-effect occurs at startup.
6. Register in Sidecar Registry: Add your runner function mapping to the AGENT_RUNNERS dictionary inside opensecai/runtime/agent_registry.py:

   AGENT_RUNNERS = {
       "dep_scan": _run_dep_scan,
       "<agent_name>": _run_<agent_name>,
   }

   Note: Registering the runner in this dictionary publishes the agent to the backend routes (GET /agents and POST /agents/{name}/run).
7. Register in Frontend (UI): Add your agent's metadata (id, name, title, description, and icon) to the AGENTS array inside desktop/src/mockData.ts so that it renders as an active tile on the dashboard:

   export const AGENTS: Agent[] = [
     {
       id: "<agent_name>", name: "<agent_name>", title: "My Scan", icon: "shield", enabled: true,
       short: "...", desc: "...", scanner: "...", scannerNote: "..."
     },
     ...
   ];

8. Add Tests: Create unit tests under tests/unit/agents/ and mocking fixtures under tests/fixtures/.

---

🧪 Testing

Note

The test directories (tests/unit/, tests/integration/, tests/e2e/) are currently scaffolded skeleton structures containing __init__.py files. Actual test cases are planned for implementation in future phases.

If you wish to set up tests, you will first need to install pytest (e.g., uv pip install pytest or add it to pyproject.toml):

# Run all unit tests once pytest is installed
uv run pytest tests/unit

# Run integration tests
uv run pytest tests/integration

---

📜 License

This project is licensed under the Apache 2.0 License. See the LICENSE file for more information.