Blacksmith：開源的 AI 驅動滲透測試框架

Navigation Menu

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

To see all available qualifiers, see our documentation.

Uh oh!

There was an error while loading. Please reload this page.

BlacksmithAI is an OPEN-SOURCE advanced penetration testing framework that leverages multiple AI agents to automate security assessments. The system orchestrates specialized agents through a complete penetration testing lifecycle, from reconnaissance to post-exploitation using professional security tools in a controlled environment.

License

Uh oh!

There was an error while loading. Please reload this page.

yohannesgk/blacksmith

Folders and files

Latest commit

History

Repository files navigation

BlacksmithAI

[OPEN-SOURCE] AI-Powered Penetration Testing Framework

An intelligent multi-agent system for automated security assessment and penetration testing.

Documentation • Quick Start • Architecture • Tools

Table of Contents

Overview

BlacksmithAI is an opensource advanced penetration testing framework that leverages multiple AI agents to automate security assessments. The system orchestrates specialized agents through a complete penetration testing lifecycle—from reconnaissance to post-exploitation—using professional security tools in a controlled environment.

Key Features

Use Cases

Architecture

BlacksmithAI uses a hierarchical multi-agent system.

Agent Hierarchy

Orchestrator

Specialized Subagents

Each agent has access to specific tools tailored to its role, ensuring efficient and focused operations.

Prerequisites

System Requirements

Software Dependencies

We rely on the following tools:

1. Python: uv

uv is a fast, modern Python package manager + environment tool — kind of like a turbocharged combo of pip, pipx, and virtualenv. ([GitHub][1])

Install uv

If you prefer a Python-packaged version:

Verify:

Notes:

2. Docker & Docker Compose

Docker lets us containerize and run backend services, databases, etc.

Install on Ubuntu / Debian

macOS

After installing, start Docker Desktop and confirm:

If you see version outputs, you’re good to go.

Tip: On Linux you may want to add your user to the docker group:

3. Node.js 18+

We use Node.js for frontend tooling. Node 18+ is required for modern pnpm and ecosystem compatibility. ([docs.pyloid.com][3])

Ubuntu / Debian

macOS

Install with Homebrew:

Verify:

4. pnpm (Fast JavaScript Package Manager)

pnpm is preferred for consistent, fast installs and predictable lockfiles. ([pnpm.cn][4])

Install pnpm

You can install via one of these:

Verify:

Verify Your Dev Environment

Try these checks:

vLLM setup

if you want to use vLLM local models

setup vLLM

Serve

Installation

Step 1: Clone the Repository

Step 2: Install Python Dependencies

Step 3: Build the mini-kali Docker Image

The mini-kali container provides all penetration testing tools in a secure, isolated environment.

Step 4: Install Frontend Dependencies (Optional)

Skip this if using the terminal-only interface.

Quick Start with Makefile

For a simpler setup experience, use the provided Makefile commands. Run make help to see all available commands.

Complete Setup (One-Command)

This command performs:

Initial Configuration

After running make setup, configure your environment:

Running BlacksmithAI

This command:

The Web UI requires multiple terminals. Run these commands in separate terminals:

Then access: http://localhost:3000

Using VLLM (Local LLM)

Available Makefile Commands

Quick Reference

Configuration

Environment Variables

Create a .env file from the example:

Edit .env and add your API key:

No environment variables needed. Ensure your VLLM server is running:

Application Configuration

Edit blacksmithAI/config.json to configure LLM providers and models.

you can support for more providers like openai, claude,...and many more. by simply editing config.json and adding api key to .env

you can easily scaleup with the above method and add more support.

Usage

Option 1: Terminal Interface (CLI)

Interact directly through the terminal with full agent control.

Follow the prompts to initiate penetration testing tasks.

Option 2: Web UI

Access a modern, user-friendly interface for managing penetration tests.

Access the UI at: http://localhost:3000

Option 3: Cloud Version

A hosted version is available for quick testing without local setup.

Tools & Capabilities

BlacksmithAI provides access to professional penetration testing tools through the mini-kali Docker container. All tools are designed for non-interactive, stdin/stdout execution—ideal for AI agents.

Reconnaissance Tools

Build the attack surface map through passive and active information gathering.

Scanning & Enumeration

Deep dive into discovered targets to identify services and vulnerabilities.

Vulnerability Analysis

Map services to known vulnerabilities and assess security risks.

Exploitation Tools

Execute controlled exploits and validate vulnerabilities.

Post-Exploitation

Assess impact and identify pivot opportunities after successful exploitation.

General Utilities

Support tools for various tasks.

Upcoming Features

Agent Workflow

BlacksmithAI follows a structured penetration testing methodology through coordinated agent execution.

1. Orchestrator Agent

Role: General Commander

The orchestrator is the central coordination point that:

Available Tools: planning tools, filesystem tools

2. Reconnaissance Agent

Role: Attack Surface Mapping

Builds a comprehensive map of the target environment:

Available Tools: Reconnaissance tools, general utilities

3. Scanning & Enumeration Agent

Role: Deep Inspection

After attack surface mapping, this agent:

Available Tools: Scanning & enumeration tools, general utilities

4. Vulnerability Analysis Agent

Role: Risk Assessment

Analyzes outputs from scanning to:

Available Tools: Vulnerability mapping tools, general utilities

5. Exploitation Agent

Role: Proof-of-Concept Execution

Validates vulnerabilities through controlled exploitation:

Available Tools: Exploitation tools, general utilities

6. Post-Exploitation Agent

Role: Impact Assessment

After successful exploitation:

Available Tools: Post-exploitation tools, general utilities

Workflow Visualization

Troubleshooting

Docker Issues

Container won't start

Port conflicts

LLM Provider Issues

OpenRouter connection errors

VLLM connection errors

Frontend Issues

Build errors

UI not connecting

Agent Performance

Slow responses

Agent stuck in loop

Common Errors

"Module not found"

"Permission denied"

Documentation

For more detailed information, refer to:

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting pull requests.

License

This project is open-source:

The source code is available under the GPL‑3.0‑only open‑source license for community use, modification, and redistribution (see LICENSE-GPL.txt).

For commercial use under different terms (for example, closed‑source distribution or integration without copyleft obligations), please contact us to obtain a commercial license.

You may choose which license to comply with when you use the code.

[Contact me]📧(mailto:[email protected])

Support

Built with ❤️ for the security community

About

BlacksmithAI is an OPEN-SOURCE advanced penetration testing framework that leverages multiple AI agents to automate security assessments. The system orchestrates specialized agents through a complete penetration testing lifecycle, from reconnaissance to post-exploitation using professional security tools in a controlled environment.

Resources

License

Uh oh!

There was an error while loading. Please reload this page.

Stars

Watchers

Forks

Releases

Sponsor this project

Uh oh!

There was an error while loading. Please reload this page.

Packages

  0

Uh oh!

There was an error while loading. Please reload this page.

Languages

Footer

Footer navigation