需要对 LLM/AI 模型做安全扫描、OWASP LLM…

适用于部署前后对 API 型或浏览器聊天型 LLM 目标运行 garak 探针、查看 ASR、导出 PDF 并接入 SIEM/告警。

适用场景

解决思路

1. 快速安装：执行 `curl -sL https://raw.githubusercontent.com/0din-ai/ai-scanner/main/scripts/install.sh | bash`。
2. 手动安装：执行 `curl -O https://raw.githubusercontent.com/0din-ai/ai-scanner/main/dist/docker-compose.yml` 和 `curl -O https://raw.githubusercontent.com/0din-ai/ai-scanner/main/.env.example`，然后执行 `cp .env.example .env`。
3. 生成安全密钥：执行 `openssl rand -hex 64`，把输出写入 `.env` 的 `SECRET_KEY_BASE`，并将 `POSTGRES_PASSWORD` 设置为强密码。
4. 启动服务：执行 `docker compose up -d`；访问 `http://localhost`；默认凭据为 `admin@example.com` / `password`，首次登录后立即修改默认密码。
5. 配置 `.env` 必需项：设置 `SECRET_KEY_BASE=<64-byte-hex>` 和 `POSTGRES_PASSWORD=<strong-password>`。
6. 配置 `.env` 可选项：按需设置 `PORT=8080`；SIEM 设置 `SPLUNK_HEC_URL=https://splunk.example.com:8088/services/collector`、`SPLUNK_HEC_TOKEN=$SPLUNK_HEC_TOKEN`、`RSYSLOG_HOST=syslog.example.com`、`RSYSLOG_PORT=514`；邮件设置 `SMTP_HOST=smtp.example.com`、`SMTP_PORT=587`、`SMTP_USERNAME=$SMTP_USERNAME`、`SMTP_PASSWORD=$SMTP_PASSWORD`。
7. 创建 API-based LLM Target：使用 `Target.create!(name: 'Production GPT-4', target_type: 'api', api_endpoint: 'https://api.openai.com/v1/chat/completions', api_key: ENV['OPENAI_API_KEY'], model_name: 'gpt-4', organization: current_organization)`。
8. 创建 Browser-based Chat UI Target：使用 `Target.create!(name: 'Internal Chatbot UI', target_type: 'browser', url: 'https://chatbot.internal.example.com', organization: current_organization)`。
9. 通过 UI 运行扫描：进入 `Targets` → 选择 target → 点击 `New Scan` → 选择 probe families 或 individual probes → 点击 `Run Scan`。
10. 通过 Rails Console 运行按需扫描：`scan = Scan.create!(target: target, probe_families: ['prompt_injection', 'data_leakage', 'insecure_output'], organization: current_organization)`，然后 `ScanJob.perform_later(scan.id)`。
11. 创建计划重复扫描：`ScheduledScan.create!(target: target, probe_families: ['prompt_injection', 'jailbreak'], cron_expression: '0 2 * * 1', organization: current_organization)`，例如每周一 2am 运行。
12. 列出所有 probe families：`Garak::ProbeRegistry.families`。
13. 获取某个 family 下的 probes：`Garak::ProbeRegistry.probes_for('prompt_injection')`；总共有 179 probes across 35 families。
14. 查看 ASR 和状态：`scan = Scan.find(scan_id)`；`scan.asr_score`；`scan.status`；`scan.probe_results.count`。
15. 查看逐 probe 结果：遍历 `scan.probe_results`，输出 `result.probe_name`、`result.passed? ? 'SAFE' : 'VULNERABLE'`、`result.attempt_count`、`result.asr_score`。
16. 趋势跟踪：使用 `target.scans.completed.order(:created_at).map { |scan| { date: scan.created_at, asr: scan.asr_score } }` 比较同一 target 的 ASR 变化。
17. 导出 PDF：`pdf_path = ReportExporter.export_pdf(scan)`；或通过 UI 进入 completed scan → `Export PDF`；报告包含 executive summary、per-probe results、per-attempt drill-down。
18. 配置 Splunk SIEM：在 `config/initializers/siem.rb` 中设置 `SiemIntegration.configure do |config| config.provider = :splunk; config.splunk_hec_url = ENV['SPLUNK_HEC_URL']; config.splunk_hec_token = ENV['SPLUNK_HEC_TOKEN']; config.forward_on_completion = true; end`。
19. 配置 Rsyslog SIEM：在 `config/initializers/siem.rb` 中设置 `config.provider = :rsyslog`、`config.rsyslog_host = ENV['RSYSLOG_HOST']`、`config.rsyslog_port = ENV['RSYSLOG_PORT'].to_i`。
20. 创建组织：`org = Organization.create!(name: 'Security Team Alpha')`。
21. 邀请用户：`User.invite!(email: 'analyst@example.com', organization: org, role: 'analyst')`；角色可为 `admin`、`analyst`、`viewer`；数据按 organization 自动加密，`org.encryption_key` 自动管理。
22. 开发环境安装：`git clone https://github.com/0din-ai/ai-scanner.git`；`cd ai-scanner`；`cp .env.example .env.development`；`bundle install`；`rails db:create db:migrate db:seed`；`pip install garak`；`bin/dev`。
23. 运行测试与 lint：`bundle exec rspec`；或 `bundle exec rspec spec/models/scan_spec.rb`、`bundle exec rspec spec/jobs/scan_job_spec.rb`；执行 `bundle exec rubocop`。
24. 部署前测试新 LLM：创建 target；用 `Garak::ProbeRegistry.families` 创建 scan 运行全部 35 个 probe families；执行 `ScanJob.perform_now(scan.id)`；若 `scan.reload.asr_score > 0.15`，输出 WARNING 并在部署前审查；否则输出 PASS: Model meets security threshold。
25. 使用 Mock LLM 验证扫描器配置：`Target.create!(name: 'Mock LLM', target_type: 'mock', organization: current_organization)`；运行快速扫描验证端到端配置。
26. 扫描完成 Webhook：在 `config/initializers/scan_hooks.rb` 中 `ActiveSupport::Notifications.subscribe('scan.completed') do |_, _, _, _, payload| scan = Scan.find(payload[:scan_id]); if scan.asr_score > 0.20; SlackNotifier.alert(channel: '#security-alerts', message: "High ASR detected: #{scan.asr_score} on #{scan.target.name}"); end; end`。
27. Docker Compose 生产覆盖：在 `docker-compose.override.yml` 的 `web` 服务设置 `RAILS_ENV: production`、`FORCE_SSL: 'true'`，并添加 Traefik labels，例如 `traefik.enable=true`、`traefik.http.routers.scanner.rule=Host(`scanner.example.com`)`、`traefik.http.routers.scanner.tls.certresolver=letsencrypt`。
28. 升级 ai-scanner：`docker compose pull`；`docker compose up -d`；`docker compose exec web rails db:migrate`。
29. 排查 scan stuck in 'running'：检查 `docker compose logs worker`，garak Python 进程可能崩溃。
30. 排查启动时 `SECRET_KEY_BASE` 错误：运行 `openssl rand -hex 64` 并设置到 `.env`。
31. 排查无法连接 target API：验证 API key 环境变量已设置；检查防火墙允许容器出站。
32. 排查 browser target 扫描失败：确保 worker 容器内有 Playwright/Chrome。
33. 排查 PDF 导出空白：检查 web 容器内是否安装 `wkhtmltopdf`。
34. 排查 SIEM 收不到事件：验证 `SPLUNK_HEC_URL` 包含完整路径 `/services/collector`。
35. 查看全部服务日志：`docker compose logs -f`。
36. 查看 worker 日志：`docker compose logs -f worker`。
37. 进入 Rails console 调试：`docker compose exec web rails console`。
38. 检查 garak 是否工作：`docker compose exec worker python -c 'import garak; print(garak.__version__)'`。
39. 贡献者定位关键文件：`app/models/scan.rb`（ASR 计算）、`app/models/target.rb`、`app/models/probe_result.rb`、`app/jobs/scan_job.rb`、`app/services/garak_runner.rb`、`app/services/report_exporter.rb`、`app/services/siem_integration.rb`、`lib/garak/probe_registry.rb`、`dist/docker-compose.yml`、`scripts/install.sh`。

适用边界 · 注意事项

• 不想部署或维护 Rails + Docker + PostgreSQL + Python garak 环境，或只需要纯托管 SaaS 时不适用。
• 目标不是 LLM/AI 对话系统，或不需要 OWASP LLM Top 10/garak 探针覆盖时不适用。
• 没有权限向目标 API 或浏览器 UI 发起大量攻击性探针，或不允许安全测试时不要用。