deadend 0.0.1
AI agent CLI for security research
Requires Python: >=3.12

# Deadend CLI 

## Table of Contents

- [What in the world is this ?](#what-in-the-world-is-this-)
- [A quick demo](#a-quick-demo)
- [Is this another workflow that runs tools and calls it a day?](#is-this-another-workflow-that-runs-tools-and-calls-it-a-day)
- [Installation](#installation)
  - [Clone the repo](#clone-the-repo)
  - [gvisor sandbox](#gvisor-sandbox)
  - [ZAP proxy](#zap-proxy)
  - [Postgres Vector DB](#postgres-vector-db)
  - [Install with pip](#install-with-pip)
  - [Build from source](#build-from-source)
- [Usage](#usage)
  - [Environment variables](#environment-variables)
- [Roadmap](#roadmap)
- [Future Work](#future-work)
- [Architecture](#architecture)
- [Enjoy](#enjoy)

## What in the world is this ? 
Deadend CLI is a prototype AI Agent for security researchers, pentesters and developers. 

Inspired by Google Zero's project Naptime, this project aims to build a prototype of an agentic AI tool that helps gain time and give a better understanding on analysis.

## A quick demo 



## Is this another workflow that runs tools and calls it a day? 
In current state of the project, honestly, it is. Even though, it is built using a codebase indexer system, there is still work to do to make more efficient and useful on a daily basis for well-seasoned professionals. 

The project aims to build an AI-assisted vulnerability analysis system by combining code indexing and retrieval for effective security analysis. 

In other words, the goal is to simplify security analysis :
- by applying taint analysis. 
- by finding sinks and sources. 
- by connecting to specific tools to test a predicate or a complex logic that is not automatable.

This first prototype targets web application and APIs. The goal is not to replace static and dynamic analysis tools such as SASTs or DASTs, but to add a different method of analysis to find non-automatable vulnerabilities such as : 
- [ ] broken access controls 
- [ ] IDORs 
- [ ] Business logic vulnerabilities 
- [ ] and so on..





## Installation 

### clone the repo

```bash
git clone 
cd 
```

### gvisor sandbox 
The shell tool is ran in a gvisor sandbox (for obvious security concerns). 
After install docker, run the following commands : 

```bash
sudo apt update && apt install jq 
sudo gvisor_install/install_gvisor.sh
```

What the script does, is that it installs gvisor binaries and sets up docker's `daemon.json` file to be ran with gvisor instead of `runc`.  

### ZAP proxy 
We use ZAP proxy's internal API for some functionalities (ex. the crawler). Also, all the requests sent from the Agent goes to the ZAP proxy for ulterior manual analysis. 

ZAP proxy can be installed with `snap` on Ubuntu : 
```bash
sudo snap install zaproxy
``` 

Otherwise, you can download the packages and installer from the [ZAP website](https://www.zaproxy.org/download/).

> Why not use BURP you may ask? ZAP has the open-source component that is really interesting, and actually does have the same features Burp (even Pro) has. Also, we can add the Burp MCP server which will be interesting too if really needed.

### Postgres Vector DB 
To index the code source of a webpage, pgvector is used as a database to save the embeddings and relevant code sections. 


### Install with pip

### Build from source 

## Usage 
### Environment variables
Set the following environment variables:
```bash
export DATABASE_URL="postgresql://postgres:postgres@localhost:54320/codeindexerdb" # when running locally 
export OPENAI_API_KEY=sk-proj-<your-api-key>
export OPENAI_MODEL="gpt-4o"
export EMBEDDING_MODEL="text-embedding-3-small"
export ZAP_API_KEY=<za-api-key>
```

### Run examples (OWASP Juice-shop)
We take for the example the OWASP juice shop vulnerable application. 


## Roadmap and future ideas
As this project is still ongoing, here is the interesting stuff that we have in mind : 
```mermaid
kanban
    column1[To Do]
        task1[Eval : building the core eval strategy to test the agent]
        task2[Codebase indexer : optimizing the code chunking and embedding for a faster embedding]
        task3[Build in an authorization retrieval tool when a token is received or credentials are extracted or used]
    column2[In progress]
        task1[Task Description]
    Column3[Done]
    column4[canceled]
        
```

## Future Work 

## Architecture 

The architecture can be found [here](./docs/architecture.md).

## Enjoy