dhscan-agent 0.1.8
dhscan - AI-powered penetration testing
License: Apache-2.0
Requires Python: <4.0,>=3.12
Keywords: cybersecurity, security, vulnerability, scanner, pentest, agent, ai, cli


<h1 align="center">DHScan Agent</h1>
<h2 align="center">Open-source AI Hackers for your Apps</h2>

<div align="center">

[![Python](https://img.shields.io/pypi/pyversions/dhscan-agent?color=3776AB)](https://pypi.org/project/dhscan-agent/)
[![PyPI](https://img.shields.io/pypi/v/dhscan-agent?color=10b981)](https://pypi.org/project/dhscan-agent/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

</div>

<br>

---

## 🦉 Overview

DHScan provides autonomous AI agents that rapidly scan your code to discover potential security vulnerabilities. It's built for developers and security teams who need fast, efficient security feedback.

Powered by a multi-agent system, DHScan is optimized for speed, discovering potential issues without running slow validation steps. This allows your team to quickly investigate and confirm findings within your own workflow.

For detailed usage and configuration, please refer to the project's documentation.

---

## 🚀 Installation

Install DHScan Agent directly from PyPI:

```bash
pip install dhscan-agent
```

## ⚡ Quick Start

Once installed, you can start a scan with a single command. Make sure you have configured your LLM environment variables first (see below).

```bash
# Scan a web application
dhscan --target https://your-vulnerable-app.com

# Scan a local codebase
dhscan --target /path/to/your/local/code
```

---

## ⚙️ Configuration

DHScan Agent is configured via environment variables. Below are the key variables you need to set up.

### Required Variables

-   `DHSCAN_LLM`: The identifier for the language model you want to use (e.g., `openai/gpt-4o`, `ollama/llama3`). This is used by `litellm` to route requests.

### Conditionally Required

-   `LLM_API_KEY`: Your API key for the selected LLM provider. This is required for cloud-based models like OpenAI, Anthropic, etc. It can be omitted if you are using a local model via a custom base URL.

### Optional Variables

-   `LLM_API_BASE`: The base URL for the LLM API. This is essential if you are using a local model server like Ollama (`http://localhost:11434`) or LMStudio.
-   `DHSCAN_IMAGE`: Allows you to specify a custom Docker image for the sandboxed environment where tools are executed. Defaults to `sandbox:1.0`.
-   `REPORT_REPO_URL`: The URL of the Git repository where scan reports should be uploaded. Required for the `--upload-to-git` feature.
-   `REPORT_REPO_TOKEN`: A Git access token with write permissions to the report repository. Required for the `--upload-to-git` feature.

### Example Setup

```bash
# For cloud models (e.g., OpenAI)
export DHSCAN_LLM='openai/gpt-4o'
export LLM_API_KEY='your-openai-api-key'

# For local models (e.g., Ollama)
export DHSCAN_LLM='ollama/llama3'
export LLM_API_BASE='http://localhost:11434/v1' # Note: Ollama often requires /v1 suffix

# For uploading reports
export REPORT_REPO_URL='https://gitlab.com/your-group/reports.git'
export REPORT_REPO_TOKEN='your-gitlab-access-token'
export DHSCAN_IMAGE='dhyds/dh-sandbox:1.0-amd64'
```



## [!WARNING]
> Only test applications you own or have permission to test. You are responsible for using DHScan ethically and legally.