IaC Scan Runner

扫描您的基础设施即代码中常见漏洞的服务。

方面	信息
工具名称	IaC Scan Runner
Docker 镜像	xscanner/runner
PyPI 包	iac-scan-runner
文档	docs
联系我们	[email protected]

目的与描述

IaC Scan Runner 是一个 REST API 服务，用于扫描 IaC（基础设施即代码）包并执行各种代码检查，以发现可能的漏洞和改进。更多信息请参阅[文档]。

运行

本节说明如何运行 REST API。

使用 Docker 运行

你可以使用公共的 xscanner/runner Docker 镜像来运行 REST API，如下所示：

# run IaC Scan Runner REST API in a Docker container and 
# navigate to localhost:8080/swagger or localhost:8080/redoc
$ docker run --name iac-scan-runner -p 8080:80 xscanner/runner

或者你可以本地构建镜像并按如下方式运行：

# build Docker container (it will take some time) 
$ docker build -t iac-scan-runner .
# run IaC Scan Runner REST API in a Docker container and 
# navigate to localhost:8080/swagger or localhost:8080/redoc
$ docker run --name iac-scan-runner -p 8080:80 iac-scan-runner

从 CLI 运行

要使用 IaC Scan Runner CLI 运行：

# install the CLI
$ python3 -m venv .venv && . .venv/bin/activate
(.venv) $ pip install iac-scan-runner
# print OpenAPI specification
(.venv) $ iac-scan-runner openapi
# install prerequisites
(.venv) $ iac-scan-runner install
# run IaC Scan Runner REST API
(.venv) $ iac-scan-runner run

从源代码运行

要从源代码本地运行：

# Export env variables 
export MONGODB_CONNECTION_STRING=mongodb://localhost:27017
export SCAN_PERSISTENCE=enabled
export USER_MANAGEMENT=enabled

# Setup MongoDB
$ docker run --name mongodb -p 27017:27017 mongo

# install prerequisites
$ python3 -m venv .venv && . .venv/bin/activate
(.venv) $ pip install -r requirements.txt
(.venv) $ ./install-checks.sh
# run IaC Scan Runner REST API (add --reload flag to apply code changes on the way)
(.venv) $ uvicorn src.iac_scan_runner.api:app

用法与示例

这部分将展示一种可能的部署方式以及如何使用 API 调用的简短示例。

首先，我们将克隆 iac scan runner 仓库并运行 API。

$ git clone https://github.com/xlab-si/iac-scan-runner.git
$ docker compose up

完成后，你可以通过调用 localhost:8000 使用不同的 API 端点。你也可以导航到 localhost:8000/swagger 或 localhost:8000/redoc 并在那里测试所有 API 端点。在本示例中，我们将使用 curl 调用 API 端点。

让我们创建一个名为 test 的项目。

curl -X 'POST' \
  'http://0.0.0.0/project?creator_id=test' \
  -H 'accept: application/json' \
  -d ''

项目 ID 将返回给我们。在此示例中，项目 ID 是 1e7b2a91-2896-40fd-8d53-83db56088026。

例如，假设我们想要启动除 ansible-lint 之外的所有检查。让我们禁用它。

curl -X 'PUT' \
  'http://0.0.0.0:8000/projects/1e7b2a91-2896-40fd-8d53-83db56088026/checks/ansible-lint/disable' \
  -H 'accept: application/json'

现在项目已配置好，我们可以简单地选择要扫描的文件并打包成 zip。IaC-Scan-Runner 期望文件是压缩归档（通常是 zip 文件）。在这种情况下，响应类型将是 json，但可以更改为 html。请将 YOUR.zip 更改为您文件的路径。

curl -X 'POST' \
  'http://0.0.0.0:8000/projects/1e7b2a91-2896-40fd-8d53-83db56088026/scan?scan_response_type=json' \
  -H 'accept: application/json' \
  -H 'Content-Type: multipart/form-data' \
  -F '[email protected];type=application/zip'

就是这样。

使用新的检查工具扩展扫描工作流

在某些时候，可能需要将新的检查工具纳入扫描工作流，以提供更广泛的 IaC 标准和项目类型覆盖。因此，在本小节中，将识别并描述实现此目的所需的一系列步骤。然而，这些步骤需要手动执行，但计划在未来通过 API 自动化此过程，并提供用户友好的界面，帮助用户导入新工具，使其成为构成扫描工作流的可用目录的一部分。图 16 描述了扩展扫描工作流所需采取的步骤。

步骤 1 – 将工具特定类添加到 checks 目录首先，需要在 IaC Scan Runner 源代码的 checks 目录中添加一个新的工具特定 Python 类： iac-scan-runner/src/iac_scan_runner/checks/new_tool.py
新工具的类继承现有的 Check 类，该类提供了扫描工作流工具的通用化。此外，需要提供以下方法的实现：

def configure(self, config_filename: Optional[str], secret: Optional[SecretStr])
def run(self, directory: str) 第一个方法旨在提供必要的工具特定参数以进行设置（如密码、客户端 ID 和令牌），另一个方法指定如何通过 API 或 CLI 调用工具本身并返回其原始输出。

步骤 2 – 在 ScanRunner 构造函数中添加检查工具类实例一旦新的派生自 Check 的类添加到 IaC Scan Runner 的源代码中，还需要修改主类 ScanRunner 的源代码。在修改此类时，首先需要导入工具特定类，创建一个新的检查工具类实例，并将其添加到 def init_checks(self) 中的 IaC 检查字典中。 A. 导入检查工具类 from iac_scan_runner.checks.tfsec import TfsecCheck B. 在 init_checks 中创建检查工具对象的新实例 """Initiate predefined check objects""" new_tool = NewToolCheck() C. 将其添加到 init_checks 中的 self.iac_checks 字典

    self.iac_checks = {
        new_tool.name: new_tool,
        …
    }

步骤 3 – 将检查工具添加到 Compatibility 类的兼容性矩阵中另一方面，在文件 src/iac_scan_runner/compatibility.py 中，表示兼容性矩阵的字典也应扩展。有两种可能的情况：a) 应添加新文件类型作为键，以及相关工具列表作为值；b) 应将新工具添加到现有文件类型的兼容性列表中。

    compatibility_matrix = {
        "new_type": ["new_tool_1", "new_tool_2"],
        …
        "old_typeK": ["tool_1", …  "tool_N", "new_tool_3"]
    }

步骤 4 – 提供结果汇总支持最后，扫描工作流扩展所需修改序列的最后一步是修改类 ResultsSummary（src/iac_scan_runner/results_summary.py）。具体来说，需要在其方法 summarize_outcome 中添加一段代码，该代码将查找特定字符串（这些字符串是工具特定的，可用于标识检查是否通过或失败）。在遍历兼容检查的循环中，对于每个新工具，应包括以下 if-else 结构：

        if check == "new_tool":
            if outcome.find("Check pass string") > -1:
                self.outcomes[check]["status"] = "Passed"
                return "Passed"
            else:
                self.outcomes[check]["status"] = "Problems"
                return "Problems"

许可

本作品采用 Apache License 2.0 许可。

联系方式

您可以通过发送电子邮件至 [email protected] 联系 xOpera 团队。

致谢

本项目已获得欧盟 Horizon 2020 研究和创新计划的资助，资助协议号 101000162（PIACERE）。

iac-scan-runner

最受欢迎