Skip to content

Commit 53bbf02

Browse files
iammm0iammm0
committed
docs: 优化 PyPI 平台 README 展示与安装指引
1 parent 657fe46 commit 53bbf02

1 file changed

Lines changed: 110 additions & 203 deletions

File tree

‎README.md‎

Lines changed: 110 additions & 203 deletions
Original file line numberDiff line numberDiff line change
@@ -1,239 +1,146 @@
1-
<div align="center">
2-
3-
<h1 style="font-size: 3em; font-weight: bold; margin-bottom: 10px;">
4-
Secbot
5-
</h1>
6-
7-
<p style="font-size: 1.2em; color: #666; margin-bottom: 20px;">
8-
<strong>AI 驱动的自动化安全测试 CLI</strong>
9-
</p>
10-
11-
<p>
12-
<a href="https://www.python.org/downloads/">
13-
<img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python">
14-
</a>
15-
<a href="pyproject.toml">
16-
<img src="https://img.shields.io/badge/version-1.10.0-brightgreen.svg" alt="Version">
17-
</a>
18-
<a href="LICENSE">
19-
<img src="https://img.shields.io/badge/license-Custom-orange.svg" alt="License">
20-
</a>
21-
<a href="https://github.com/iammm0/secbot/releases">
22-
<img src="https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg" alt="Platform">
23-
</a>
24-
</p>
25-
26-
<p>
27-
<a href="https://github.com/langchain-ai/langchain">
28-
<img src="https://img.shields.io/badge/LangChain-0.1%2B-blueviolet.svg" alt="LangChain">
29-
</a>
30-
<a href="https://github.com/langchain-ai/langgraph">
31-
<img src="https://img.shields.io/badge/LangGraph-0.2%2B-00BFFF.svg" alt="LangGraph">
32-
</a>
33-
<a href="https://fastapi.tiangolo.com/">
34-
<img src="https://img.shields.io/badge/FastAPI-0.109%2B-009688.svg" alt="FastAPI">
35-
</a>
36-
<a href="https://www.sqlite.org/">
37-
<img src="https://img.shields.io/badge/SQLite-3.x-003B57.svg" alt="SQLite">
38-
</a>
39-
<a href="https://github.com/astral-sh/uv">
40-
<img src="https://img.shields.io/badge/uv-latest-2E86C1.svg" alt="uv">
41-
</a>
42-
</p>
43-
44-
<p>
45-
<a href="README_EN.md">English</a> | 中文
46-
</p>
47-
48-
</div>
49-
50-
---
51-
52-
> **安全警告**：本工具仅用于**获得明确授权**的安全测试、研究与教学。未经授权的网络攻击、渗透、爆破或控制行为可能违法。详见 [docs/SECURITY_WARNING.md](docs/SECURITY_WARNING.md)。
53-
54-
---
55-
56-
![Secbot 主界面](assets/secbot-main.png)
57-
58-
## 功能概览
59-
60-
- **CLI 交互**：基于 Typer + Rich 的原生终端交互，直接在进程内调用核心逻辑，无需网络通信。
61-
- **API 服务**：可选启动 FastAPI 后端，暴露 REST + SSE 接口供第三方集成。
62-
- **多智能体执行**：支持 `secbot-cli` 自动模式与 `superhackbot` 专家模式，结合规划、执行、总结链路完成安全任务。
63-
- **安全测试能力**：覆盖内网发现、端口与服务识别、Web 安全、OSINT、系统控制、防御扫描与报告生成。
64-
- **多推理后端**：内置 Ollama、DeepSeek、OpenAI、Anthropic、Gemini、Groq、OpenRouter 及多家 OpenAI 兼容厂商。
65-
- **SQLite 持久化**：对话历史、提示词链、用户偏好和 API Key 配置可持久化到 SQLite。
66-
67-
## 架构概览
68-
69-
```mermaid
70-
flowchart LR
71-
CLI["Typer CLI"]
72-
CLI -->|"进程内调用"| session["SessionManager"]
73-
session --> planner["Planner / QA / Agent Router"]
74-
planner --> tools["安全工具与系统控制"]
75-
tools --> summary["Summary / Reports"]
76-
summary --> db["SQLite"]
77-
78-
API["FastAPI /api/*（可选）"]
79-
API --> session
1+
# Secbot (Python)
2+
3+
[![PyPI version](https://img.shields.io/pypi/v/secbot.svg)](https://pypi.org/project/secbot/)
4+
[![Python versions](https://img.shields.io/pypi/pyversions/secbot.svg)](https://pypi.org/project/secbot/)
5+
[![PyPI downloads](https://img.shields.io/pypi/dm/secbot.svg)](https://pypi.org/project/secbot/)
6+
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
7+
8+
Secbot is an AI-powered security automation CLI for authorized security testing, research, and education.
9+
10+
> Security notice: use this tool only in environments where you have explicit authorization. Unauthorized scanning, exploitation, and control actions may violate laws or regulations.
11+
12+
![Secbot main UI](https://raw.githubusercontent.com/iammm0/secbot/main-py-version/assets/secbot-main.png)
13+
14+
## Why This Package
15+
16+
- CLI-first workflow built on `Typer + Rich`, with one-shot and interactive operation.
17+
- Optional FastAPI server mode for REST/SSE integration in automation pipelines.
18+
- Multi-agent execution flow (`secbot-cli` and `superhackbot`) for plan, execute, and summarize loops.
19+
- Security toolchain covering network, web, OSINT, defense scan, reporting, and system utilities.
20+
- Multi-provider LLM backends including Ollama, DeepSeek, OpenAI-compatible APIs, and more.
21+
22+
## Requirements
23+
24+
- Python `>= 3.10`
25+
- `pip` (or `uv`)
26+
- Optional: Ollama for local models
27+
28+
## Install
29+
30+
### Install from PyPI (recommended)
31+
32+
```bash
33+
pip install secbot
8034
```
8135

82-
## 环境要求
36+
If you want beta/pre-release versions:
8337

84-
- Python `3.10+`
85-
- [uv](https://github.com/astral-sh/uv)（推荐，用于同步 Python 依赖）
86-
- Ollama（可选，本地模型时需要）
38+
```bash
39+
pip install --pre secbot
40+
```
8741

88-
## 安装与启动
42+
### Install with uv
8943

90-
### 方式一：从源码运行（推荐）
44+
```bash
45+
uv pip install secbot
46+
```
47+
48+
### Install from source
9149

9250
```bash
9351
git clone https://github.com/iammm0/secbot.git
9452
cd secbot
95-
96-
# Python 依赖
9753
uv sync
54+
uv pip install -e .
9855
```
9956

100-
创建 `.env`，至少填写一组可用推理后端配置：
57+
## Quick Start
58+
59+
### 1. Configure environment variables
60+
61+
Create a `.env` file in your working directory:
10162

10263
```env
103-
# 云端推理（默认推荐）
64+
# Cloud model backend (recommended)
10465
LLM_PROVIDER=deepseek
10566
DEEPSEEK_API_KEY=sk-your-api-key
10667
DEEPSEEK_MODEL=deepseek-reasoner
10768
108-
# 或改用本地 Ollama
69+
# Optional local backend (Ollama)
10970
# LLM_PROVIDER=ollama
11071
# OLLAMA_BASE_URL=http://localhost:11434
11172
# OLLAMA_MODEL=gemma3:1b
11273
# OLLAMA_EMBEDDING_MODEL=nomic-embed-text
11374
```
11475

115-
启动：
76+
### 2. Run the CLI
11677

11778
```bash
118-
# 交互模式
119-
python main.py
120-
# 或
121-
uv run secbot
122-
123-
# 单次任务
124-
uv run secbot "扫描 192.168.1.1 的开放端口"
79+
# Interactive mode
80+
secbot
12581

126-
# 问答模式
127-
uv run secbot --ask "什么是 XSS 攻击？"
82+
# One-shot task
83+
secbot "扫描 192.168.1.1 的开放端口"
12884

129-
# 专家模式
130-
uv run secbot --agent superhackbot
85+
# Q&A mode
86+
secbot --ask "什么是 XSS 攻击？"
13187

132-
# 切换推理后端/模型
133-
uv run secbot model
88+
# Expert agent
89+
secbot --agent superhackbot
13490

135-
# 仅启动 API 服务
136-
uv run secbot server
91+
# Switch backend/model
92+
secbot model
13793
```
13894

139-
### 方式二：下载 GitHub Release
140-
141-
从 [Releases](https://github.com/iammm0/secbot/releases) 下载对应平台的 zip 包并解压，在可执行文件同目录创建 `.env` 后再运行。
142-
143-
### 方式三：安装 wheel / 本地包
95+
### 3. Start API server (optional)
14496

14597
```bash
146-
uv pip install -e .
147-
# 或
148-
pip install .
149-
```
150-
151-
安装后可使用 `secbot` / `hackbot` / `secbot-cli` 命令。
152-
153-
## 常用命令
154-
155-
| 命令 | 说明 |
156-
|------|------|
157-
| `secbot` | 进入交互模式 |
158-
| `secbot "任务描述"` | 执行单次任务 |
159-
| `secbot --ask "问题"` | 问答模式 |
160-
| `secbot --agent superhackbot` | 使用专家智能体 |
161-
| `secbot model` | 切换推理后端与模型 |
162-
| `secbot server` | 启动 FastAPI 后端服务 |
163-
| `secbot version` | 显示版本 |
164-
165-
### 交互模式内的斜杠命令
166-
167-
| 命令 | 说明 |
168-
|------|------|
169-
| `/model` | 选择推理后端、模型、API Key |
170-
| `/help` | 查看帮助 |
171-
| `exit` / `quit` | 退出 |
172-
173-
## 常见环境变量
174-
175-
| 变量 | 用途 | 默认值 |
176-
|------|------|--------|
177-
| `LLM_PROVIDER` | 当前推理后端 | `deepseek` |
178-
| `DEEPSEEK_API_KEY` | DeepSeek API Key | 无 |
179-
| `DEEPSEEK_MODEL` | DeepSeek 默认模型 | `deepseek-reasoner` |
180-
| `OLLAMA_BASE_URL` | Ollama 服务地址 | `http://localhost:11434` |
181-
| `OLLAMA_MODEL` | Ollama 默认模型 | `gemma3:1b` |
182-
| `OLLAMA_EMBEDDING_MODEL` | Ollama 嵌入模型 | `nomic-embed-text` |
183-
| `DATABASE_URL` | SQLite 路径 | `sqlite:///./data/secbot.db` |
184-
| `LOG_LEVEL` | 日志级别 | `INFO` |
185-
186-
## 目录结构
187-
188-
```text
189-
secbot/
190-
├── main.py # 入口（调用 Typer CLI）
191-
├── secbot_cli/ # CLI 入口与进程内运行器
192-
├── router/ # FastAPI 路由层（可选 API 服务）
193-
├── core/ # 智能体、执行器、规划器、记忆等核心逻辑
194-
├── tools/ # 安全工具、Web 研究、协议、报告、云安全等
195-
├── database/ # SQLite 模型与数据库管理
196-
├── hackbot_config/ # 配置、环境变量与持久化偏好
197-
├── scripts/ # 启动与构建脚本
198-
├── tests/ # 测试
199-
└── docs/ # 项目文档
98+
secbot server
20099
```
201100

202-
## 文档索引
203-
204-
| 文档 | 说明 |
205-
|------|------|
206-
| [docs/QUICKSTART.md](docs/QUICKSTART.md) | 从源码启动与常见入口 |
207-
| [docs/API.md](docs/API.md) | FastAPI REST + SSE 接口说明 |
208-
| [docs/LLM_PROVIDERS.md](docs/LLM_PROVIDERS.md) | 多厂商模型后端与配置方式 |
209-
| [docs/OLLAMA_SETUP.md](docs/OLLAMA_SETUP.md) | 本地 Ollama 配置与排障 |
210-
| [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) | 后端部署与 systemd 示例 |
211-
| [docs/DOCKER_SETUP.md](docs/DOCKER_SETUP.md) | Docker 当前策略说明 |
212-
| [docs/RELEASE.md](docs/RELEASE.md) | Release 包使用与源码打包说明 |
213-
| [docs/DATABASE_GUIDE.md](docs/DATABASE_GUIDE.md) | SQLite 结构与数据库操作 |
214-
215-
## 贡献
216-
217-
欢迎提交 Issue 和 Pull Request。
218-
219-
1. Fork 本仓库
220-
2. 创建分支：`git checkout -b feat/your-change`
221-
3. 提交修改：`git commit -m "docs: update guides"`
222-
4. 推送分支并发起 PR
223-
224-
## 许可证
225-
226-
本项目使用 [LICENSE](LICENSE) 中定义的 **Secbot Open Source License**：
227-
228-
- 允许个人学习、学术研究、教学与非营利技术交流
229-
- 修改与分发时需保留版权与协议声明
230-
- 商业用途需事先获得书面授权
231-
232-
商用授权联系：[wisewater5419@gmail.com](mailto:wisewater5419@gmail.com)
233-
234-
## 作者
235-
236-
赵明俊（Zhao Mingjun）
237-
238-
- GitHub: [@iammm0](https://github.com/iammm0)
239-
- Email: [wisewater5419@gmail.com](mailto:wisewater5419@gmail.com)
101+
## CLI Commands
102+
103+
| Command | Description |
104+
| --- | --- |
105+
| `secbot` | Start interactive mode |
106+
| `secbot "<task>"` | Run a single task |
107+
| `secbot --ask "<question>"` | Ask security questions |
108+
| `secbot --agent superhackbot` | Use expert agent mode |
109+
| `secbot model` | Configure provider/model/API keys |
110+
| `secbot server` | Run FastAPI backend |
111+
| `secbot version` | Show installed version |
112+
113+
## Common Environment Variables
114+
115+
| Variable | Purpose | Default |
116+
| --- | --- | --- |
117+
| `LLM_PROVIDER` | Active model provider | `deepseek` |
118+
| `DEEPSEEK_API_KEY` | DeepSeek API key | None |
119+
| `DEEPSEEK_MODEL` | DeepSeek model | `deepseek-reasoner` |
120+
| `OLLAMA_BASE_URL` | Ollama endpoint | `http://localhost:11434` |
121+
| `OLLAMA_MODEL` | Ollama generation model | `gemma3:1b` |
122+
| `OLLAMA_EMBEDDING_MODEL` | Ollama embedding model | `nomic-embed-text` |
123+
| `DATABASE_URL` | SQLite database URL | `sqlite:///./data/secbot.db` |
124+
| `LOG_LEVEL` | Log level | `INFO` |
125+
126+
## Documentation
127+
128+
- [Quickstart](https://github.com/iammm0/secbot/blob/main-py-version/docs/QUICKSTART.md)
129+
- [API Reference](https://github.com/iammm0/secbot/blob/main-py-version/docs/API.md)
130+
- [LLM Providers](https://github.com/iammm0/secbot/blob/main-py-version/docs/LLM_PROVIDERS.md)
131+
- [Ollama Setup](https://github.com/iammm0/secbot/blob/main-py-version/docs/OLLAMA_SETUP.md)
132+
- [Deployment](https://github.com/iammm0/secbot/blob/main-py-version/docs/DEPLOYMENT.md)
133+
- [Release Guide](https://github.com/iammm0/secbot/blob/main-py-version/docs/RELEASE.md)
134+
- [Database Guide](https://github.com/iammm0/secbot/blob/main-py-version/docs/DATABASE_GUIDE.md)
135+
- [Security Warning](https://github.com/iammm0/secbot/blob/main-py-version/docs/SECURITY_WARNING.md)
136+
137+
## Project Links
138+
139+
- Homepage: [https://github.com/iammm0/secbot](https://github.com/iammm0/secbot)
140+
- Issue Tracker: [https://github.com/iammm0/secbot/issues](https://github.com/iammm0/secbot/issues)
141+
- Releases: [https://github.com/iammm0/secbot/releases](https://github.com/iammm0/secbot/releases)
142+
- PyPI: [https://pypi.org/project/secbot/](https://pypi.org/project/secbot/)
143+
144+
## License
145+
146+
This project is licensed under MIT. See [LICENSE](LICENSE) for details.

0 commit comments

Comments
 (0)