## https://sploitus.com/exploit?id=EF0259D9-5C4F-5B8C-B136-6597A7DC8E43
# ExploitSense
ExploitSense is a local-first vulnerability analysis tool that scans your code for real security issues and then, only when you ask, uses a local AI model to explain exactly what's wrong, how an attacker would exploit it, and how to fix it properly.
Nothing leaves your machine without your explicit action. No cloud APIs. No telemetry. No subscriptions.
---
## What it does
When you drop in a Python file (or paste some code), ExploitSense runs it through Bandit and a custom rule engine that covers the OWASP Top 10. Every finding gets normalized into a clean structure with a severity level, CWE reference, and the exact line where the issue lives. You see results in a fast, dark-themed dashboard that groups findings by severity.
The AI part only kicks in when you click the Explain button on a specific finding. At that point, ExploitSense sends a minimal, sanitized snippet to your local Ollama instance running mistral-nemo. The response comes back as a six-section report covering the vulnerability summary, why it exists, how an attacker would use it, a realistic attack example, a code-level fix, and best practices. The second time you ask about the same issue, nothing calls the model at all โ it's served instantly from the local SHA-256 cache.
---
## What you need before starting
You need Python 3.11 or newer, Node.js 18 or newer, and Ollama installed and running. Once Ollama is up, pull the model:
```bash
ollama pull mistral-nemo:latest
```
If you want Python code scanning via Bandit to work (it's the best scanner in the system), install it alongside the other backend dependencies. JavaScript scanning is optional and works if you have ESLint installed globally.
---
## Getting the backend running
First, copy the environment template:
```bash
cp .env.example .env
```
The defaults in that file are fine for a local setup. Then install the Python dependencies and start the API server:
```bash
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload
```
The API will be live at http://localhost:8000. You can hit `/health` to confirm it's up.
---
## Getting the frontend running
In a separate terminal:
```bash
cd frontend
npm install
npm run dev
```
Then open http://localhost:5173. That's it.
---
## Running the tests
From the backend directory:
```bash
cd backend
pytest tests/ -v
```
The test suite covers the Python and HTTP scanners, the normalizer, and the caching layer. The Ollama dependent tests use mocks so they work fully offline. If Bandit isn't installed, those tests skip themselves cleanly instead of failing.
---
## Using the CLI
If you'd rather scan from the terminal without the UI, there's a Click-based CLI. From the project root:
```bash
python cli/exploitsense_cli.py scan backend/tests/fixtures/vuln_python.py
```
You can also export results to JSON:
```bash
python cli/exploitsense_cli.py scan backend/tests/fixtures/vuln_python.py --output results.json
```
And if you already have a scan ID from a previous run, you can pull the full report:
```bash
python cli/exploitsense_cli.py report
```
---
## Running with Docker
If you want everything containerized:
```bash
docker-compose up --build
```
The backend runs on port 8000, the frontend on port 5173. Ollama still needs to be running on your host machine the containers reach it via `host.docker.internal`.
---
## Adding your own detection rules
The rule engine loads any `.py` file you drop into a `rules/` directory inside the backend. Each file just needs to export a `RULES` list. Here's what a rule looks like:
```python
import re
RULES = [
{
"name": "my_custom_rule",
"pattern": re.compile(r"your_pattern_here", re.I),
"vuln_type": "HARDCODED_SECRET",
"severity": "HIGH",
"description": "What this rule catches and why it matters.",
}
]
```
Drop the file in, restart the backend, and the rule is active. No code changes needed anywhere else.
---
## How the AI caching works
Every time you click Explain, ExploitSense computes a SHA-256 hash of the vulnerability type, the sanitized snippet, and whether learning mode is on. If that hash exists in the local SQLite database, the cached explanation is returned immediately Ollama is never called. This means if you scan the same code twice, or if two separate files have the same vulnerability pattern, the AI only does work once.
---
## Configuring the model
The model is set in your `.env` file:
```
OLLAMA_MODEL=mistral-nemo:latest
```
You can change this to any model you have pulled locally. Smaller models like `llama3.2` respond faster. Larger models give more thorough explanations. The timeout is also configurable โ bump `OLLAMA_TIMEOUT` if you're running a slow machine or a very large model.
---
## Project layout
The backend lives in `backend/app` and is broken into scanners (one per language), a detection layer that normalizes findings, an AI module that handles prompts and caching, a store layer for SQLite, and a FastAPI layer with three routes: scan, explain, and report.
The frontend is a Vite + React + TypeScript app with a typed API client, per-finding hooks, and a component tree that goes App โ Dashboard โ VulnCard โ ExplainPanel.
The CLI in `cli/exploitsense_cli.py` talks directly to the scanner and store without going through the HTTP API, so it works without the backend server running.
---
## A note on privacy
ExploitSense was built on the assumption that your code is sensitive. The sanitizer strips API keys, tokens, passwords, and email addresses from any snippet before it's sent anywhere. Full files are never sent to the AI only the specific snippet around the finding, capped at 500 characters. And even that only happens when you explicitly click Explain.