Metadata-Version: 2.4
Name: wakeupdexter
Version: 1.0.2
Summary: A local-first, agentic application security assessment CLI.
Author: Team Dexter, Kartik Pagariya, Vikrant Kadam, Aditya Dengale, Pranali Yelavikar
License-Expression: MIT
Project-URL: Homepage, https://dexter.tech
Project-URL: Repository, https://github.com/kartikpagariya25/dexter
Keywords: security,pentest,vulnerability-scanner,cli,sast,dast,appsec
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Testing
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"

![Dexter Logo](https://github.com/VikrantKadam028/VikrantKadam028/blob/main/DEXTER%20LOGO.png?raw=true)

### *"He doesn't just find flaws. He verifies them."*

**Local-first, agentic application security assessment — that investigates its own findings before it trusts them.**

[![PyPI](https://img.shields.io/pypi/v/wakeupdexter?color=crimson&label=PyPI&logo=pypi&logoColor=white)](https://pypi.org/project/wakeupdexter/)
[![Python](https://img.shields.io/pypi/pyversions/wakeupdexter?color=blue&logo=python&logoColor=white)](https://pypi.org/project/wakeupdexter/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](#license)
![Tests](https://img.shields.io/badge/tests-65%20passing-brightgreen?logo=pytest&logoColor=white)
![SAVR Loop](https://img.shields.io/badge/loop-Scan→Analyze→Verify→Refine-8A2BE2)
![Sandboxed](https://img.shields.io/badge/sandbox-Docker%20isolated-2496ED?logo=docker&logoColor=white)
![Tools](https://img.shields.io/badge/tools-14%20integrated-orange)

Dexter doesn't run a fixed set of checks and dump a static report. It runs every scan through a closed loop — **Scan → Analyze → Verify → Refine** — that investigates its own findings before it trusts them.

```
dexter --target ./your-project -n --instruction "prioritize secrets and access control"
```

---

## Why Dexter?

Most vulnerability scanners share the same weaknesses: high false-positive rates, no correlation between tools, and no transparent path from "flagged" to "confirmed." Dexter's Verify stage is a real tool-calling agent (ReAct pattern) — it reads surrounding code, computes entropy on suspected secrets, and greps the codebase for related usage before handing back a plain-English verdict instead of just a severity label.

Every tool can also run sandboxed: a disposable, per-scan Docker container instead of your host machine. See [Docker Sandbox](#docker-sandbox).

## The SAVR Loop

| Stage | What happens |
|---|---|
| **Scan** | 14 integrated tools + local static-analysis rules |
| **Analyze** | Base confidence score assigned per finding |
| **Verify** | Agentic investigation — reads code, checks entropy, searches the repo |
| **Refine** | Instruction-aware confidence boost, bounded by a circuit breaker |

Both entry points — the one-shot `dexter` CLI (CI-friendly, non-zero exit on findings) and the interactive `wakeupdexter` REPL — call the same underlying engine. No logic is duplicated between them.

---

## Quickstart

```bash
python -m venv .venv
.venv\Scripts\activate        # Windows — use `source .venv/bin/activate` on macOS/Linux
pip install wakeupdexter

dexter --target ./your-project -n --instruction "prioritize secrets and access control"
wakeupdexter                  # or launch the interactive command center
```

**Recommended:** build the sandbox once so tools don't need host installation.

```bash
dexter sandbox build
set DEXTER_SANDBOX=1          # Windows CMD — PowerShell: $env:DEXTER_SANDBOX="1"
dexter --target ./your-project -n
```

---

## Docker Sandbox

With `DEXTER_SANDBOX=1` set, every containerized tool runs inside a disposable, per-run container. The target is bind-mounted read-only at `/workspace`, and the container is destroyed the moment the scan finishes. No per-platform tool installs, no PATH issues, no Windows-specific tool ports.

```bash
dexter sandbox build                  # fast path (~5–10 min)
dexter sandbox build --with-browser   # + Chromium/agent-browser (~20–30 min, not yet used by any adapter)
dexter sandbox status                 # check Docker + image status
```

If Docker isn't available, Dexter prints a notice and falls back to running tools on the host — `DEXTER_SANDBOX=1` is always safe to leave set.

> **Scanning something running on your own machine?** Containers don't share the host's `localhost`. Use Docker Desktop's special DNS name instead:
> ```bash
> dexter authorize http://host.docker.internal:5000
> dexter --target http://host.docker.internal:5000 -n
> ```

---

## Integrated Tools

14 tools total, spanning SAST, secrets, dependency CVEs, and authorized recon/DAST.

| Tool | Type | Gate | Sandboxed |
|---|---|---|:---:|
| Semgrep | SAST | none | ✅ |
| Bandit | Python SAST | none | ✅ |
| Gitleaks | Secrets | none | ✅ |
| Trufflehog | Secrets + live-credential check | none | ✅ |
| Trivy | Dependency CVEs | none | ✅ |
| Retire.js | Frontend dependency CVEs | none | ✅ |
| ESLint (security ruleset) | JS/TS SAST | none | ✅ |
| ast-grep | Structural SAST | none | ✅ |
| httpx | Recon / fingerprint | authorization | ✅ |
| katana | Web crawler | authorization | ✅ |
| ffuf | Content discovery | authorization | host-only |
| Nmap | Port/service recon | authorization | host-only |
| Nuclei | Template-based DAST | authorization | host-only |
| Nikto | Web misconfig | authorization | host-only* |
| OWASP ZAP | DAST | authorization + running daemon | host-only |
| sqlmap | Exploitation | authorization + `exploit` command | host-only |
| jwt_tool | JWT weakness testing | `exploit` command | host-only |
| Metasploit | Exploitation | — | not auto-wired, by design |

\* Perl-based; needs Strawberry Perl on Windows.

Full sandbox parity for the host-only tools is tracked in [Roadmap](#roadmap).

---

## Safety & Authorization

Dexter treats "authorized targets only" as enforced behavior, not a suggestion:

- Live-target tools refuse to run against anything not explicitly added via `dexter authorize <target>`.
- Exploitation-tier tools (`sqlmap`, `jwt_tool`) are structurally outside the automatic scan registry — enforced by a dedicated test, not just convention.
- Exploit-tier actions require an explicit, separate command and a confirmation prompt in the interactive dashboard — never triggered by a normal scan.
- Metasploit has no automatic invocation at all.
- Even authorized, sandboxed scans mount the target read-only.

**Only test systems you own or have explicit written permission to assess.**

---

## Usage

```bash
dexter --target ./app --scan-mode standard
dexter -n -t ./app --instruction "Prioritize authentication and access control"
dexter --target-list ./targets.txt --run-name ci-scan

dexter report ci-scan --format human
dexter report ci-scan --format markdown --output report.md
dexter view ci-scan

dexter tools
dexter auth
dexter authorize <target>

dexter exploit sqlmap "<url>" --param id
dexter exploit jwt_tool "<jwt>"

dexter sandbox build [--with-browser]
dexter sandbox status

wakeupdexter    # interactive REPL
```

Inside `wakeupdexter`:

```
scan <path-or-url> [instructions]              full SAVR loop
/semgrep, /bandit, /gitleaks, /trivy <path>    run one tool directly
/nmap, /nuclei, /nikto, /zap, /ffuf <target>   run one live-target tool (needs authorize first)
exploit sqlmap <url> --param <name>            explicit exploitation step, asks for confirmation
authorize <target>                             allow a live target for gated tools
/tools                                         show installed/missing tool status
runs · report [run] [human] · view [run] · pool
```

Exit status is non-zero when findings are present — `-n` mode is CI-safe.

---

## LLM Provider Setup

Create `~/.dexter/.env` (Windows: `%USERPROFILE%\.dexter\.env`):

```
DEXTER_LLM_KEYS=key-one,key-two,key-three
```

| Variable | Purpose |
|---|---|
| `DEXTER_LLM_KEYS` | Comma-separated key pool. A 429 cools that key down and rotates to the next. |
| `DEXTER_LLM_BASE_URL` | Any OpenAI-compatible endpoint — Groq by default. |
| `DEXTER_LLM_LOCAL_URL` | Fallback tier when every pooled key is cooling — point at local Ollama or llama.cpp. |
| `DEXTER_LLM_COOLDOWN_SECONDS` | Cooldown duration per key (default 5 hours). |

`dexter auth` shows live status of every key and the local fallback. Dexter functions fully offline with zero API keys via its deterministic fallback.

> Never commit a real key. If one ends up in a scanned project's `.env`, Dexter's own Gitleaks/Trufflehog adapters will correctly flag it — that's not a false positive, rotate it.

---

## Architecture

```
                     dexter (CLI)        wakeupdexter (interactive REPL)
                          │                        │
                          └────────────┬───────────┘
                                        ▼
                              dexter.loop.run_savr()
                                        │
        ┌───────────────┬──────────────┼──────────────┬───────────────┐
        ▼               ▼              ▼               ▼               ▼
      SCAN           ANALYZE        VERIFY          REFINE          REPORT
```

```
containers/Dockerfile     sandbox image (Kali-based)
src/dexter/
├── cli.py                one-shot CLI entry point
├── dashboard.py          wakeupdexter interactive REPL
├── loop.py               the SAVR loop; opens/tears down the sandbox per target
├── agentic_verify.py     ReAct tool-calling verification agent
├── tools.py              external tool adapters + registry (sandbox-aware)
├── sandbox.py            per-run Docker container lifecycle
├── scanner.py            local static-analysis rules
├── provider_pool.py      LLM key rotation + tool-calling support
├── authorization.py      authorized-target list
├── report.py             human-language report generation
├── env_file.py           ~/.dexter/.env loader
└── wordlists/common.txt  bundled ffuf wordlist
tests/                    65 tests, isolated from network/tool/Docker availability
```

---

## Roadmap

- Full sandbox parity for Nmap, Nuclei, Nikto, ffuf, sqlmap, jwt_tool
- Cross-tool finding correlation & deduplication
- Agentic Analyze and Refine stages
- Multi-agent coordinator spawning per-stage subagents
- Historical run diffing across scans
- Browser-driven verification (Chromium/agent-browser already installable via `--with-browser`)
- Metasploit resource-script passthrough
- Revisit the web dashboard (currently shelved on `backup-web-platform`)

---

## Team

| Name | Role |
|---|---|
| Kartik R. Pagariya | |
| Vikrant K. Kadam | |
| Aditya U. Dengale | |
| Pranali D. Yelavikar | |
| Dr. Parikshit Mahalne | Project Guide |

VIT — AI & Data Science, Final Year Project

## License

MIT

---

**Only test systems you own or have explicit written permission to assess.**
