Skill Scanner Python SDK与REST API参考如何3步构建企业级技能安全扫描流水线【免费下载链接】skill-scannerSecurity Scanner for Agent Skills项目地址: https://gitcode.com/gh_mirrors/sk/skill-scannerSkill Scanner是一款面向 AI Agent 技能Agent Skills的安全扫描工具提供 Python SDK 与 REST API 两种编程接口帮助开发者将技能包安全检查无缝嵌入自动化流水线。本文带你快速上手 Skill Scanner Python SDK 的核心 API掌握 7 个 REST 端点的使用方法并给出一套可直接落地的企业级技能安全扫描流水线构建方案。一、为什么需要编程接口CLI之外的两条路Skill Scanner 默认提供命令行工具覆盖绝大多数本地扫描场景。但当你需要把扫描能力嵌入产品或平台时就需要编程接口 官方在 docs/user-guide/api-rationale.md 中给出了清晰的选型建议接口适用场景特点CLI本地开发、一次性扫描、脚本化检查零依赖、即装即用Python SDK同一运行时内的程序化扫描类型化模型、可组合分析器REST APICI/CD 集成、Web 上传门户、分布式服务HTTP 原生、异步批量任务一句话总结本地用 SDK跨系统用 API。二、Python SDK 快速上手5行代码完成首次扫描一键安装步骤pip install cisco-ai-skill-scanner最小扫描示例SDK 的核心是SkillScanner类定义在 skill_scanner/scanner.py。一次扫描只需要 5 行代码from skill_scanner import SkillScanner scanner SkillScanner() result scanner.scan_skill(/path/to/skill) print(result.max_severity, len(result.findings))返回的ScanResult是类型化模型常用属性包括is_safe无 CRITICAL/HIGH 发现时为True可直接作为流水线门禁条件max_severity最高严重级别CRITICAL → SAFE 六级findings发现列表每条含rule_id、severity、file_path、remediation修复建议analyzers_used本次实际运行的分析器便于审计批量扫描与结果聚合扫描整个技能仓库用scan_directory返回聚合的Reportreport scanner.scan_directory(./skills, recursiveTrue, check_overlapTrue) print(report.total_findings, report.critical_count)check_overlapTrue会额外执行跨技能描述重叠分析识别名称混淆类风险——这是平台型场景很有价值的能力。完整参数说明见 docs/user-guide/python-sdk.md。用扫描策略统一团队标准企业内不同业务线对可接受风险的定义不同Skill Scanner 通过ScanPolicy在不改代码的情况下调整扫描行为from skill_scanner.core.scan_policy import ScanPolicy policy ScanPolicy.from_preset(strict) # 或 from_yaml(my_policy.yaml) scanner SkillScanner(policypolicy)内置 5 个预设选型速查表预设定位建议场景strict最大敏感度审计与威胁狩猎balanced默认均衡通用 CI 门禁low-noise降低告警量自己技能的日常扫描quiet最小告警量评审人力有限的场景permissive宽松可信内部技能详细对比见 docs/user-guide/scan-policies-overview.md。运行时挂载高级分析器默认分析器静态规则 字节码 管道污点分析即可覆盖大部分威胁。需要更强检测时用add_analyzer动态挂载from skill_scanner.core.analyzers import LLMAnalyzer scanner.add_analyzer(LLMAnalyzer(modelanthropic/claude-sonnet-4-20250514))LLM 分析器支持 Anthropic、OpenAI、Azure、Bedrock、Gemini 等提供方API Key 通过环境变量SKILL_SCANNER_LLM_API_KEY注入切勿硬编码 更多组合方式可参考 examples/programmatic_usage.py 与 examples/advanced_scanning.py。三、REST API 参考7个端点支撑扫描服务启动 Skill Scanner API ServerAPI 服务基于 FastAPI一条命令即可启动默认监听localhost:8000skill-scanner-api --port 8000启动后访问/docs可获得自动生成的 Swagger 交互式文档。服务定义位于 skill_scanner/api/router.py。端点速查表端点方法用途/healthGET健康检查返回可用分析器列表/scanPOST按本地目录路径扫描单个技能/scan-uploadPOST上传技能 ZIP 包并扫描CI/CD 主场景/scan-batchPOST启动异步批量扫描返回scan_id/scan-batch/{scan_id}GET轮询批量任务状态与结果/analyzersGET列出全部分析器及能力说明每个端点都支持相同的扫描开关policy策略预设或自定义 YAML 路径、use_llm、use_behavioral、use_virustotal、llm_consensus_runsLLM 多数投票次数等。完整请求/响应 Schema 见 docs/user-guide/api-endpoints-detail.md快速验证只需curl http://localhost:8000/healthZIP 上传扫描Web 门户的核心工作流/scan-upload接收 multipart 表单file: skill.zip服务端解压到私有临时目录、扫描后自动清理。内置防护上限单包 50 MB、ZIP 条目 500 个、解压后 200 MB天然防御 zip 炸弹攻击 ️异步批量扫描大仓库的正确姿势/scan-batch以后台任务运行客户端轮询获取结果curl -X POST http://localhost:8000/scan-batch \ -H Content-Type: application/json \ -d {skills_directory: /srv/skills, policy: balanced}批量结果保存在内存有界缓存中最多 1000 个任务、1 小时 TTL。Python 客户端示例参考 examples/api_usage.py 和 examples/batch_scanning.py。四、企业级技能安全扫描流水线构建指南架构总览三层防线结合 SDK 与 API推荐的企业级流水线分三层开发侧SDK工程师在本地用SkillScanner做 pre-commit 快速自检使用low-noise预设控制噪音CI 门禁API 批量提交触发/scan-batch全量扫描发现 CRITICAL 即失败阻断合并平台侧API 上传内部技能市场通过/scan-upload在入库前扫描外部提交的技能包。关键配置路径白名单与密钥管理API 服务默认拒绝一切文件系统访问只允许私有上传目录。要让/scan读取本地技能目录必须显式设置白名单export SKILL_SCANNER_ALLOWED_ROOTS/srv/skills:/srv/scanner-configLLM 能力按需启用全部走环境变量注入SKILL_SCANNER_LLM_API_KEY、SKILL_SCANNER_LLM_MODEL配合密钥管理服务杜绝密钥入库。安全加固清单⚠️ API 服务默认无认证切勿直接暴露公网——它可能被用于 API Key 滥用攻击或服务拒绝攻击。生产部署前完成以下加固官方指引见 docs/user-guide/api-operations.md✅ 添加X-API-Key请求头认证FastAPI 原生支持✅ 使用 slowapi 等中间件限流如 10 次/分钟✅ 置于 nginx/Caddy 反向代理之后启用 TLS✅ 只绑定内网地址通过/health端点做持续健康监控✅ 接入 Prometheus 暴露指标纳入告警体系容器化交付官方文档给出了标准 Dockerfile 模板python:3.11-slim 基础镜像、非 root 用户运行、EXPOSE 8000。构建后一条命令即可部署docker run -p 8000:8000 -e SKILL_SCANNER_LLM_API_KEY*** skill-scanner-api五、常见问题与排查问题排查方法服务无法启动用lsof -i :8000检查端口占用换--port 8080LLM 分析器不可用重装pip install -U cisco-ai-skill-scanner确认模型环境变量扫描速度慢改用/scan-batch批量端点、开启结果缓存上传被拒绝 413压缩 ZIP 至 50 MB 以内完整错误码对照表见 docs/user-guide/api-endpoints-detail.md。六、延伸阅读 Python SDK 完整参考docs/user-guide/python-sdk.md API 服务与端点详情docs/user-guide/api-server.md 生产运维与 CI/CDdocs/user-guide/api-operations.md 扫描策略详解docs/user-guide/scan-policies-overview.md 示例脚本examples/basic_scan.py、examples/integration_example.py小结Skill Scanner 的 Python SDK 让安全扫描像调用普通函数一样简单REST API 则让扫描能力成为可被 CI/CD 与 Web 平台消费的服务。按照本文的三层架构落地你就能为 AI Agent 技能生态筑起一道企业级安全防线 【免费下载链接】skill-scannerSecurity Scanner for Agent Skills项目地址: https://gitcode.com/gh_mirrors/sk/skill-scanner创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考