快速上手

相关源文件

本页面内容基于以下源文件生成：

• scripts/install.sh
• strix/interface/cli.py
• docs/quickstart.mdx
• strix/config/config.py
• strix/interface/main.py
• strix/telemetry/tracer.py
• strix/interface/tui.py
• strix/llm/config.py
• strix/config/init.py
• strix/interface/utils.py

Strix 是一个基于 AI 的自动化渗透测试工具，通过 Docker 沙箱提供安全的漏洞扫描环境。本文档将指导完成从环境准备到首次扫描的完整流程。

环境要求与安装

系统依赖

运行 Strix 需要满足以下前提条件：

• Docker：必须处于运行状态，用于执行安全沙箱环境
• LLM API 密钥：支持 Strix Router 或自带第三方提供商密钥

官方文档明确指出 Docker 是必要依赖，首次运行时会自动拉取沙箱镜像（docs/quickstart.mdx:6-9）。

支持的平台

安装脚本自动检测操作系统和 CPU 架构，支持以下组合：

检测逻辑通过 uname 命令获取系统信息，并对 macOS Rosetta 转译环境进行特殊处理（scripts/install.sh:19-50）。不支持的系统组合会导致安装终止并显示错误信息。

安装方式

提供两种推荐的安装方式：

方式一：curl 安装（推荐）

bash
1curl -sSL https://strix.ai/install | bash

此方式从官方脚本获取最新版本并自动配置环境（docs/quickstart.mdx:13-17）。

方式二：pipx 安装

bash
1pipx install strix-agent

适用于已配置 Python 环境的用户（docs/quickstart.mdx:19-23）。

Docker 环境验证

安装脚本会检查 Docker 是否可用，并在 Docker 守护进程未运行时给出提示（scripts/install.sh:177-192）。沙箱镜像默认使用 ghcr.io/usestrix/strix-sandbox:0.1.12，首次运行时自动拉取（scripts/install.sh:194-205）。

配置 LLM 提供商

环境变量配置

Strix 通过环境变量配置 LLM 模型和 API 密钥。支持两种配置模式：

模式一：Strix Router（推荐）

bash
1export STRIX_LLM="strix/gpt-5"
2export LLM_API_KEY="your-strix-api-key"

模式二：自带 API Key

bash
1export STRIX_LLM="openai/gpt-5"
2export LLM_API_KEY="your-api-key"

官方推荐使用 strix/gpt-5、strix/claude-opus-4.6 或 strix/gpt-5.2 以获得最佳效果（docs/quickstart.mdx:26-47）。

配置参数管理

配置类 Config 集中管理所有 LLM 相关参数，包括：

这些参数在配置类中定义并支持环境变量覆盖（strix/config/config.py:14-36）。

运行首次扫描

最小可运行命令

完成环境配置后，使用以下命令启动首次扫描：

bash
1strix --target ./your-app

此命令会对本地代码库目录执行安全扫描（docs/quickstart.mdx:49-53）。

启动流程

CLI 入口函数 run_cli 负责初始化扫描配置并显示启动面板。扫描配置包含以下关键信息：

• scan_id：运行标识符
• targets：目标信息列表
• user_instructions：用户自定义指令
• run_name：运行名称

启动面板显示目标地址和输出目录路径（strix/interface/cli.py:23-82）。

首次运行注意事项

首次运行时，系统会自动拉取 Docker 沙箱镜像，可能需要几分钟时间。扫描结果保存在 strix_runs/<run-name> 目录下（docs/quickstart.mdx:55-57）。

目标类型与使用场景

支持的目标类型

Strix 支持多种目标类型，适应不同的安全测试场景：

官方文档提供了各类目标的使用示例（docs/quickstart.mdx:59-75）。

多目标支持

CLI 支持同时指定多个目标进行白盒测试。当存在多个目标时，启动面板会显示目标数量和详细列表（strix/interface/cli.py:29-43）。单目标显示原始地址，多目标显示计数和逐项列表。

运行时与输出

实时进度显示

扫描过程中，CLI 通过 Live 组件实时更新状态面板，每 2 秒刷新一次。状态面板显示当前渗透测试进度和统计信息（strix/interface/cli.py:125-140）。

漏洞实时报告

当发现漏洞时，系统通过回调函数 display_vulnerability 实时输出漏洞详情。每个漏洞以独立面板形式展示，包含漏洞 ID 和详细报告（strix/interface/cli.py:89-103）。

信号处理与清理

CLI 注册了以下信号处理器确保资源正确释放：

• SIGINT（Ctrl+C）
• SIGTERM
• SIGHUP（如果系统支持）

退出时自动调用 cleanup_runtime 清理运行时环境（strix/interface/cli.py:107-120）。

最终报告输出

扫描完成后，系统输出总结报告面板，包含完整的渗透测试摘要。报告面板使用蓝色边框标识，与扫描中的绿色状态面板区分（strix/interface/cli.py:182-201）。

运行时配置参数

运行时行为可通过以下参数调整：

这些参数在配置类中定义（strix/config/config.py:42-46）。

常见问题与排错

问题一：Docker 未安装或未运行

症状：安装或运行时提示 "Docker not found" 或 "Docker daemon not running"

解决方案：

1. 安装 Docker：访问 https://docs.docker.com/get-docker/
2. 启动 Docker 守护进程
3. 手动拉取沙箱镜像：docker pull ghcr.io/usestrix/strix-sandbox:0.1.12

安装脚本会在检测到 Docker 问题时给出相应提示（scripts/install.sh:179-191）。

问题二：不支持的操作系统或架构

症状：安装时显示 "Unsupported OS/Arch: xxx/xxx"

解决方案： 确认系统在支持列表中：Linux x86_64、macOS x86_64/arm64、Windows x86_64。安装脚本会检测并拒绝不支持的组合（scripts/install.sh:43-49）。

问题三：沙箱镜像拉取失败

症状：首次运行时提示 "Failed to pull sandbox image"

解决方案：

1. 检查网络连接和 Docker 配置
2. 手动执行：docker pull ghcr.io/usestrix/strix-sandbox:0.1.12
3. 如果使用代理，确保 Docker 正确配置代理设置

安装脚本会在镜像拉取失败时提示可手动拉取（scripts/install.sh:199-204）。

问题四：API 密钥配置错误

症状：扫描启动失败或 LLM 调用超时

解决方案：

1. 确认环境变量正确设置：echo $STRIX_LLM 和 echo $LLM_API_KEY
2. 验证 API 密钥有效性
3. 检查网络是否能访问对应的 LLM API 端点

配置类支持多种 LLM 提供商的参数配置（strix/config/config.py:14-36）。

问题五：扫描中断后资源未释放

症状：Ctrl+C 中断后 Docker 容器残留

解决方案： CLI 已实现信号处理机制，正常中断时会自动清理资源。如果异常中断导致残留，可手动清理：

bash
1docker ps -a | grep strix-sandbox | awk '{print $1}' | xargs docker rm -f

信号处理逻辑确保 SIGINT、SIGTERM 和 SIGHUP 都能触发清理（strix/interface/cli.py:113-121）。

下一步建议

完成首次扫描后，建议进一步探索以下内容：

1. CLI 选项：了解所有命令行参数，包括扫描模式、深度控制等高级选项
2. 扫描模式：根据目标特性选择合适的扫描深度（快速/标准/深度）
3. 多目标策略：学习如何组合本地代码和在线目标进行综合测试
4. 结果解读：深入理解漏洞报告格式和修复建议

扫描结果目录 strix_runs/<run-name> 包含完整的测试日志和漏洞详情，可用于后续分析和报告生成（strix/interface/cli.py:40-43）。