subkoks/hacker-agent

# hacker-agent [](https://github.com/subkoks/hacker-agent/actions/workflows/ci.yml) [](https://github.com/subkoks/hacker-agent/releases/latest) [](https://www.python.org/downloads/) [](LICENSE) [](https://github.com/astral-sh/uv) 面向授权测试人员、研究人员和开发者的永久记忆**安全研究**与**逆向工程**代理工具包。 基于 Python **3.13** 的软件包，采用 `uv`、`pydantic`、`httpx` 和 `typer`，提供 SQLite 记忆、CVE/CISA KEV 引入、审计检查清单、Ghidra MCP 目录以及 Stake Engine 数学辅助功能。 ## 仓库布局 ``` src/hacker_agent/ ├── config.py # Path + env resolution (no hardcoded absolute paths) ├── memory/ # SQLite knowledge base + Pydantic models ├── cli/ # Typer CLI (`python -m hacker_agent` / `hacker-agent`) ├── cve/ # NVD + CISA KEV importer (direct HTTP, no subprocess) ├── stake/ # Provably-fair game math + RGS templates ├── audit/ # Security-audit checklist generator └── ghidra/ # Ghidra MCP tool catalog + memory bridge scripts/ # Bash automation (auto-mode, auto-commit) tests/ # pytest suite data/ # Default SQLite location (gitignored; `.gitkeep` tracked) ``` ## 系统要求 | 要求 | 说明 | |-------------|--------| | **Python 3.13+** | `pyproject.toml` 中的 `requires-python = ">=3.13"`。[`pyenv`](https://github.com/pyenv/pyenv) 匹配锁定的 `.python-version`。 | | **[uv](https://github.com/astral-sh/uv)** | 推荐的安装与任务运行器（`uv sync`、`uv run …`）。 | | **Bash + 常用 Unix 实用工具** | `scripts/auto-mode.sh` 使用 `bash`、`find`、`tar`、`git`。macOS 和 Linux 为首选平台；不支持 Windows，除非通过 **WSL2** 使用。 | ## 安装说明 ### 1. 克隆并进入目录 ``` git clone https://github.com/subkoks/hacker-agent.git cd hacker-agent git checkout develop # default integration branch; use tags for releases ``` ### 2. 创建环境 **使用 uv（推荐）** ``` # 仅限 Production / runtime dependencies uv sync # 添加 dev tools (pytest, ruff, mypy, bandit, respx) uv sync --extra dev ``` **使用 pip（可编辑安装）** ``` python3.13 -m venv .venv source .venv/bin/activate # Linux / macOS # .venv\Scripts\activate # Windows cmd (unsupported except WSL) pip install -U pip pip install -e ".[dev]" # or pip install -e . without dev extras ``` 任何可编辑安装完成后，当虚拟环境被激活时，控制台脚本 `hacker-agent` 即可使用。对于未激活 Shell 的 **uv**，请使用 `uv run hacker-agent …`（参见[运行说明](#run)）。 ### 3. 可选：验证 ``` uv run hacker-agent --version uv run python -m hacker_agent --version ``` ## 配置与环境变量 1. 复制模板：`cp .env.example .env` 并根据您的机器修改相应的值。 2. **此软件包不会自动加载 `.env`。** 请在 Shell 中手动导出变量、使用 [`direnv`](https://direnv.net/) 或包装命令，例如： set -a && source .env && set +a && uv run hacker-agent dashboard 解析的路径是**相对于项目根目录的**，除非给定的是绝对路径（参见 `src/hacker_agent/config.py`）。 | 变量 | 用途 | 默认值 | |----------|---------|---------| | `HACKER_DATA_DIR` | SQLite 和默认转储路径的目录 | `/data` | | `HACKER_MEMORY_DB` | SQLite 数据库文件 | `/hacker-memory.db` | | `HACKER_LOG_DIR` | `auto-mode` / `auto-commit` 日志 | `/logs` | | `HACKER_BACKUP_DIR` | `auto-mode` tar 包备份 | `/backups` | | `HACKER_AUTO_INTERVAL` | `scripts/auto-mode.sh start` 守护进程循环的间隔秒数 | `3600` | | `NVD_API_BASE` | NVD CVE 2.0 JSON endpoint | `.env.example` 中的公共 NVD URL | | `CISA_KEV_URL` | CISA KEV JSON feed URL | 官方 CISA URL | | `AUTO_COMMIT_BRANCH_PREFIX` | 在 `main`/`master` 上运行 `scripts/auto-commit.sh` 时创建分支的前缀 | `auto/` | | `GHIDRA_PROJECT_DIR` | 默认 Ghidra 项目目录提示（`GhidraIntegration`） | `~/Projects/ghidra-re/projects` | | `GITHUB_TOKEN` | **当前不会被 Python 包读取**；保留供您可能在此基础上添加的本地 GitHub 自动化使用（例如 `gh` auth）。 | _(空)_ | 显示解析后的数据库路径： ``` uv run hacker-agent memory path ``` ## 运行说明 ### 日常 CLI（本地 / “生产”） 使用 **uv**（无需手动 `activate`）： ``` uv run hacker-agent --help uv run python -m hacker_agent --help ``` 在通过 `pip install -e .` **激活**的虚拟环境中： ``` hacker-agent --help python -m hacker_agent --help ``` 没有单独的长期运行服务器进程；每条命令在执行完毕后即退出。 ### 开发命令 在本地镜像 CI： ``` uv run ruff check src tests uv run ruff format --check src tests uv run mypy src uv run pytest -q --cov=src/hacker_agent ``` 有关分支流程（发布时通过 `develop` → PR → `main`）和审查期望，请参阅 [`CONTRIBUTING.md`](CONTRIBUTING.md)。 ## 用法示例 ``` # Knowledge ops hacker-agent learn --content "JWT 'none' alg bypass" --category technique --importance 8 hacker-agent recall --query "JWT" --limit 5 hacker-agent dashboard # CVE feed import (NVD + CISA KEV — network required) hacker-agent cve import --days 7 hacker-agent cve import --kev-only # Audit checklists hacker-agent audit list hacker-agent audit generate --type web-application --format markdown # Stake-style RGS math (simulation helpers) hacker-agent stake verify-rtp --game crash --rounds 100000 # Ghidra MCP catalog + workflow text (see below) hacker-agent ghidra tools hacker-agent ghidra guide ``` ## Cursor、编辑器与 Ghidra MCP - **Cursor / VS Code**：打开克隆的仓库文件夹。使用集成终端运行 `uv run hacker-agent …`。可选的项目子代理位于 [`.cursor/agents/`](.cursor/agents/)；仓库规则在 [`AGENTS.md`](AGENTS.md) 中。如需链接预览图，请在 GitHub 仓库的 **Settings → General → Social preview** 下上传 [`.github/social-preview.png`](.github/social-preview.png)（需在 **1 MB** 以内；为安全起见可使用 [`.github/repository-open-graph-template.png`](.github/repository-open-graph-template.png) 的边距）。 - **Ghidra MCP**：`ghidra` 包子模块列出了**预期的 MCP 工具名称**，并将**工作流指南**打印到标准输出。反汇编和 MCP 调用在您由 Ghidra 支持的 MCP 服务器和主机代理中执行，而不是在 `hacker-agent` 内部执行。在您的编辑器中接入 Ghidra MCP 服务器，然后当磁盘上有 JSON / 反编译产物时，使用 `hacker-agent ghidra record` 将快照持久化到 SQLite 中。 ## 自动化脚本 (`scripts/`) `scripts/auto-mode.sh` 可运行健康检查、tar 包备份（当 CLI 成功时包括大脑导出）、通过 `auto-commit.sh` 的可选自动提交以及轻量级上游通知。**守护进程 / 备份路径要求 `python3` 和 `python3 -m hacker_agent` 位于 `PATH` 中**（您的虚拟环境或 uv shim）。 ``` export PATH="$PWD/.venv/bin:$PATH" # example after venv activate scripts/auto-mode.sh once # single cycle scripts/auto-mode.sh start # background daemon (uses HACKER_AUTO_INTERVAL) scripts/auto-mode.sh status scripts/auto-mode.sh stop scripts/auto-mode.sh health # one-shot compile + CLI smoke scripts/auto-mode.sh backup # backup only ``` `scripts/auto-commit.sh` 在从 `main`/`master` 运行时，会在安全的特性分支上创建提交，并在存在 `origin` 时尝试 `git push`——请按照您通常推送的方式配置 Git 凭据 / SSH。 ## 安全与合规 - 将导入的**大脑转储**、**CVE JSON** 和 **Ghidra 分诊文件**视为不受信任的输入；严格控制 `HACKER_MEMORY_DB` 和备份的文件系统权限。 - **NVD API** 调用使用公共 endpoint；请遵守 [NIST 使用期望](https://nvd.nist.gov/developers/start-here)及您公司的出站策略。此代码库中**尚未**接入 `NVD_API_KEY`。 - **切勿**将此工具用于未经明确授权测试的系统。 ## 质量关卡 ``` ruff check src tests ruff format --check src tests mypy src pytest -q ``` （推荐使用如[开发命令](#development-commands)中所示的 `uv run …`。） ## 链接 - 仓库: - 最新发行版: - 问题追踪: - NVD CVE 2.0 API: - CISA KEV 目录: - Stake Engine 文档: ## 贡献 有关开发设置、分支流程和代码规范，请参阅 [`CONTRIBUTING.md`](CONTRIBUTING.md)。漏洞报告请通过 [`docs/SECURITY.md`](docs/SECURITY.md) 提交，请勿使用公开的 Issues。社区准则位于 [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)。用户可见的变更记录在 [`docs/CHANGELOG.md`](docs/CHANGELOG.md) 中。 ## 许可证 [MIT](LICENSE)

标签：AI代理, CISA KEV, Cursor, CVE, Ghidra, GPT, httpx, MCP, NVD, pydantic, Python, Python 3.13, RGS, SQLite, typer, uv, XSS, 云资产清单, 博彩数学, 安全规则引擎, 审计清单, 密码管理, 对称加密, 持久化存储, 数字签名, 数据展示, 无后门, 无线安全, 游戏模板, 漏洞分析, 漏洞情报, 漏洞管理, 红队, 网络安全, 网络安全审计, 自动化审计, 记忆库, 路径探测, 运行时操纵, 逆向工程, 隐私保护