kennasecurity/toolkit

Kenna工具包镜像文档

概述和主要用途

Kenna工具包是围绕Kenna Security漏洞管理平台的一套数据和API操作工具集。它被组织为“任务”——可从Docker或Podman命令行调用和交互的功能单元，用于简化平台的数据处理和API集成操作。

核心功能和特性

• 任务化功能：功能以“任务”为单元组织，支持命令行直接调用
• 多容器支持：兼容Docker和Podman容器工具
• 灵活部署：支持直接运行预构建镜像、在GitHub Actions中集成或自定义构建镜像
• 参数传递：支持为任务传递自定义参数以指定行为
• 数据持久化：通过卷挂载实现输入输出文件的读写
• 代理兼容：支持通过Docker/Podman内置代理配置访问网络

使用场景和适用范围

• 需要对Kenna Security平台进行数据和API操作的用户
• CI/CD环境中集成Kenna Security操作（如GitHub Actions）
• 开发自定义Kenna Security集成功能的场景
• 需要批量处理Kenna Security平台数据的自动化任务

系统要求

• 支持运行独立Docker镜像的容器工具：
  • Podman
  • Docker
• 8GB RAM
• 网络访问能力

详细使用方法

运行最新镜像

最简单的入门方式是使用Docker Hub上的预构建镜像。

首次使用示例：拉取最新镜像并打印任务列表

bash
docker pull kennasecurity/toolkit && docker run -it kennasecurity/toolkit

检查API密钥示例：拉取最新镜像并执行检查API密钥的任务（以expanse任务为例）

bash
docker pull kennasecurity/toolkit && docker run -it kennasecurity/toolkit task=kenna_api_key_check kenna_api_key=$KENNA_API_KEY

有关API密钥使用的说明，请参考API认证文档。

在GitHub Actions上运行

可利用CI/CD可用时长在GitHub Actions上运行工具包。详细说明请参考https://github.com/KennaSecurity/All_Samples/tree/master/no_server_toolkit_run_git_actions%E3%80%82

构建自己的镜像

如果修改了代码或需要自定义构建镜像，可按以下步骤操作：

使用Docker构建：

bash
docker build . -t toolkit:latest

使用Podman构建：

bash
podman build . -t toolkit:latest

启动自己的容器镜像

构建完成后，可启动自定义镜像：

Docker启动：

bash
docker run -it --rm toolkit:latest

Podman启动：

bash
podman run -it --rm toolkit:latest

调用特定任务

要使用工具包功能，需传递task=[任务名称]变量。

Docker调用特定任务：

bash
docker run -it --rm toolkit:latest task=example

Podman调用特定任务：

bash
podman run -it --rm toolkit:latest task=example

带参数调用任务

任务可能需要参数来指定行为，参数格式为空格分隔的"arg=val"字符串。

获取任务帮助：

bash
# 查看任务参数帮助
docker run -it --rm -t toolkit:latest task=csv2kdi:help
# 查看任务详细说明
docker run -it --rm -t toolkit:latest task=csv2kdi:readme

示例：带参数调用aws_inspector任务
Docker:

bash
docker run -it --rm -t toolkit:latest task=aws_inspector aws_region=us-east-1 aws_access_key=$AWS_ACCESS_KEY aws_secret_key='$AWS_SECRET_KEY'

Podman:

bash
podman run -it --rm -t toolkit:latest task=aws_inspector aws_region=us-east-1 aws_access_key=$AWS_ACCESS_KEY aws_secret_key='$AWS_SECRET_KEY'

API数据输入输出

许多任务需要输入输出JSON或日志文件，通过Docker卷挂载实现：

• 默认输入目录：/opt/toolkit/input
• 默认输出目录：/opt/toolkit/output

配置卷挂载示例
Docker:

bash
docker run  -it --rm \
-v ~/Desktop/toolkit_input:/opt/app/toolkit/input \
-v ~/Desktop/toolkit_output:/opt/app/toolkit/output \
-t toolkit:latest task=example

Podman:

bash
podman run  -it --rm \
-v ~/Desktop/toolkit_input:/opt/app/toolkit/input \
-v ~/Desktop/toolkit_output:/opt/app/toolkit/output \
-t toolkit:latest task=example

工具包功能（任务）

查看当前可用任务列表，请访问https://github.com/KennaSecurity/toolkit/tree/main/tasks/readme.md%E3%80%82

高级用法

代理配置：如需通过代理使用容器，建议使用Docker或Podman的内置代理支持：

• Docker代理配置
• Podman代理配置

帮助我们改进

发现错误时，请创建GitHub issue并详细描述错误，团队将尽快解决。https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-an-issue%E3%80%82

所有工具包功能请求请发送至：***。

开发指南

拉取请求

如修复了bug、增强了任务或添加了新任务，请提交拉取请求：

1. Fork本仓库
2. 在功能分支中进行修改（请包含测试！）
3. 确保 lint 检查通过且所有测试通过（可使用act本地运行检查）
4. https://github.com/KennaSecurity/toolkit/compare%EF%BC%8C%E5%B0%86%E5%8A%9F%E8%83%BD%E5%88%86%E6%94%AF%E5%90%88%E5%B9%B6%E5%88%B0%E6%9C%AC%E4%BB%93%E5%BA%93%E7%9A%84main%E5%88%86%E6%94%AF%EF%BC%88%E8%80%8C%E9%9D%9E%E4%BD%A0%E7%9A%84fork%EF%BC%89

!https://github.com/jgarber/toolkit/assets/8061/c3c5cca7-f8af-427f-a932-6f798d91c7e1

QA

如需将/output文件夹上传到本地开发环境，请运行：

bash
bundle exec ruby toolkit.rb task=your-task kenna_api_host=your-local-api-host

前提条件：UI中生成的API令牌，符合.ruby-version中指定的Ruby版本

贡献者

• @kenna-bmcdevitt (API客户端)
• @linda (原始脚本)
• @jgamblin (容器工作)
• @dbro (初始实现和测试，各种任务)
• @jcran (初始实现，各种任务)
• @jdoss (容器工作)
• @caleb-eckenwiler (文档)

安全徽章

!https://github.com/KennaPublicSamples/toolkit/workflows/Lint%20Code%20Base/badge.svg !https://github.com/KennaPublicSamples/toolkit/workflows/Bundler%20Audit/badge.svg