securelens-backend

 ██████╗███████╗ ██████╗██╗   ██╗██████╗ ███████╗██╗     ███████╗███╗   ██╗███████╗
██╔════╝██╔════╝██╔════╝██║   ██║██╔══██╗██╔════╝██║     ██╔════╝████╗  ██║██╔════╝
╚█████╗ █████╗  ██║     ██║   ██║██████╔╝█████╗  ██║     █████╗  ██╔██╗ ██║███████╗
 ╚═══██╗██╔══╝  ██║     ██║   ██║██╔══██╗██╔══╝  ██║     ██╔══╝  ██║╚██╗██║╚════██║
██████╔╝███████╗╚██████╗╚██████╔╝██║  ██║███████╗███████╗███████╗██║ ╚████║███████║
╚══════╝╚══════╝ ╚═════╝ ╚═════╝ ╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝╚═╝  ╚═══╝╚══════╝

An AI-native AppSec agent and local security auditor. Autonomously triage and scan codebases against the OWASP Top 10, probe live web infrastructure, generate threat narratives, and engage in interactive triage chat sessions directly from your terminal or CI/CD pipelines.

Core Capabilities
How It Works (Multi-Agent Pipeline)
Quick Start
CLI Command Guide
Supported Providers
API Endpoints Summary
Architecture & Tech Stack
Roadmap
License

Core Capabilities

SecureLens provides a dual-component security environment to verify application safety at the code level and infrastructure level:

Autonomous Code Auditor: Rather than scanning blindly, SecureLens acts like an AppSec engineer. It triages repositories to locate high-risk files (auth handlers, DB layers, configs), performs concurrent OWASP Top 10 analysis, and synthesizes findings into actionable remediation guidance.
Web Infrastructure Prober: Run deep probes on live URLs checking 30+ parameters across SSL/TLS strength, Cookie flags, transport policies, and exposure vectors. It computes an overall security score and uses AI to write a threat chain narrative showing how attackers might combine weaknesses.
Interactive CLI Companion: Work locally with custom ignore filters, offline signature checks, local PDF report compiles, and direct synchronization of findings back to the server console.

How It Works (Multi-Agent Pipeline)

SecureLens runs a decomposed three-phase orchestrator to ensure highly targeted, context-aware analysis:

flowchart TD
    A([Target Codebase]) --> B[Phase 1: Triage]
    
    subgraph B ["Phase 1: Triage"]
        B1["Fetch file tree / list local paths"]
        B2["LLM isolates high-risk files\n(auth, db, configurations)"]
        B1 --> B2
    end
    
    B --> C[Phase 2: Concurrent Analysis]
    
    subgraph C ["Phase 2: Concurrent Analysis"]
        C1["Decompose tasks into individual jobs"]
        C2["Run asyncio.gather() throttled\nvia rate-limiting Semaphores"]
        C3["Perform OWASP Top 10 auditing\nand return structured Pydantic schema"]
        C1 --> C2 --> C3
    end
    
    C --> D[Phase 3: Synthesis & REPL]
    
    subgraph D ["Phase 3: Synthesis & REPL"]
        D1["Aggregate multi-agent findings"]
        D2["Compile overall security score\nand exportable PDF report"]
        D3["Launch interactive Q&A REPL\nfor follow-up patches"]
        D1 --> D2 --> D3
    end
    
    D --> E([Final Verified Audit])

Quick Start

SecureLens consists of a central backend server (managing scans, JWT authentication, and historical tracking) and an interactive CLI tool.

1. Deploy Backend Server

Standard Docker Compose (Recommended)

Launch the server along with PostgreSQL instantly:

cp .env.example .env
docker compose up --build

Manual Development Setup (SQLite)

git clone https://github.com/Rarebuffalo/securelens-backend.git
cd securelens-backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn app.main:app --reload

The dev server defaults to http://127.0.0.1:8000. Database is automatically initialized.

2. Install Local CLI

Choose one of the following installation methods based on your platform and preferences:

Method A: One-Line Global Installation (Cross-Platform)

Recommended for general use. Installs the CLI globally on Windows, macOS, or Linux directly from the repository without needing to clone it manually:

pip install git+https://github.com/Rarebuffalo/securelens-backend.git#subdirectory=cli

(Or use pipx install git+... to automatically isolate the tool in its own environment).

Method B: Local Source Installation (Development)

If you have cloned this repository locally:

# On Linux/macOS
chmod +x cli/install.sh
./cli/install.sh
source venv/bin/activate

# On Windows or manual setup
pip install -e cli/

3. Configure CLI

Initiate configuration with the interactive wizard to set up API keys and point to your server:

securelens configure

This saves credentials, preferred models, and settings to your local profile at ~/.securelens/config.yaml.

CLI Command Guide

Scan Codebases

Analyze local codebases. SecureLens automatically triages your file tree, ignoring builds/artifacts, runs the selected model, and drops you into a chat.

securelens scan .                              # Scan current folder
securelens scan ./project                      # Scan specific directory
securelens scan . --model gpt-4o               # Specify model override
securelens scan . --no-ai                      # Run lightning-fast offline regex pattern scan
securelens scan . --sync                       # Upload scan results automatically to backend
securelens scan . --ci --fail-on high          # CI pipeline mode: exits with non-zero on High vulnerabilities

Audit Web Infrastructure

Probe a live target website for transport layer security, configurations, and header exposure.

securelens web https://example.com             # Scan target URL
securelens web https://my-app.com --no-ai      # Raw scanner check without AI summary
securelens web https://my-app.com --output md  # Save results to markdown file

Interactive Triage REPL

When running a code scan, SecureLens starts an interactive terminal shell (REPL) allowing you to query vulnerability details and export findings.

Ask a follow-up (or press Ctrl+C to exit)
Type /help for available commands

> Explain the SQL injection found in db.py and write a patch
> Which files have critical severity issues?
> /files
> /export pdf
> /exit

Supported REPL Slash Commands

/help — Display CLI commands helper
/files — List files selected for AI triage
/score — Print the current codebase security grade (A-F)
/export markdown — Save audit to markdown report
/export pdf — Compile styled PDF audit document locally
/model <name> — Switch AI models mid-session
/exit — Terminate the interactive REPL

Supported Providers

SecureLens leverages LiteLLM under the hood. You can configure any model matching your credential flags:

Provider	Model Identifier	Config Required
Google Gemini (Default)	`gemini/gemini-2.0-flash`	`GEMINI_API_KEY`
OpenAI	`gpt-4o`, `gpt-4o-mini`	`OPENAI_API_KEY`
Anthropic	`claude-3-5-sonnet-latest`, `claude-3-5-haiku-20241022`	`ANTHROPIC_API_KEY`
Ollama	`ollama/llama3.1`	Run local Ollama server

API Endpoints Summary

Interact with the server via the standard REST endpoints or use the interactive documentation at /docs:

Area	Method	Route	Description	Auth
System	`GET`	`/health`	Verify server status	No
Auth	`POST`	`/auth/register`	Register new profile	No
Auth	`POST`	`/auth/login`	Retrieve access token	No
Code Scan	`POST`	`/code-scan/analyze`	Trigger Git repository triage & audit	Yes
Code Scan	`POST`	`/code-scan/sync`	Sync local scanner results to database	Yes
Code Scan	`POST`	`/code-scan/chat`	Continue chat discussion about code scan	Yes
Web Scan	`POST`	`/scan`	Audit a URL's network security	Optional
History	`GET`	`/scans`	List historical scan records	Yes
History	`DELETE`	`/scans/{id}`	Purge a scan record from DB	Yes

Architecture & Tech Stack

SecureLens uses a modern, lightweight async tech stack:

Backend Engine: Python 3.12+, FastAPI, SQLAlchemy 2.0 (Async DB support), Pydantic v2.
Database Layer: PostgreSQL (Docker production deployment) / SQLite (Aiosqlite for local development).
AI Adapter: LiteLLM provider client with structured JSON parsing constraints.
CLI Utility: Click (CLI parser), Rich (terminal style/color engine), PyYAML.
Local Exporters: FPDF2 (PDF generation).

Roadmap

Local Offline Scanner — Execute regex-based pattern scans on offline environments.
Terminal PDF Generation — Native local PDF output via CLI.
Server Synchronisation — Push local CLI findings to central PostgreSQL dashboards.
CI/CD Integration Packages — Dedicated GitHub Actions and GitLab Runner wrappers.
Dependency Audit (securelens audit) — Check packages against the OSV DB.
Automated Patches (Git MRs) — Generate Git PRs directly from CLI fixes.

License

This repository is licensed under the MIT License. See LICENSE for details.

Happy Hacking! Keep your codebases secure.

README.md

Table of Contents