Package: iac-scan-runner
IaC Scan RunnerService that scans your Infrastructure as Code for common vulnerabilities.AspectInformationTool nameIaC Scan RunnerDocker imagexscanner/runnerPyPI packageiac-scan-runnerDocumentationdocsContact usxopera@xlab.siTable of ContentsDescriptionRunningRun with DockerRun from CLIRun from sourceLicenseContactAcknowledgementPurpose and descriptionTheIaC Scan Runneris a REST API service used to scan IaC (Infrastructure as Code) package and perform various
code checks in order to find possible vulnerabilities and improvements.
Explore thedocsfor more info.RunningThis section explains how to run the REST API.Run with DockerYou can run the REST API using a publicxscanner/runnerDocker image as follows:#runIaCScanRunnerRESTAPIinaDockercontainerand#navigatetolocalhost:8080/swaggerorlocalhost:8080/redoc$dockerrun--nameiac-scan-runner-p8080:80xscanner/runnerOr you can build the image locally and run it as follows:#buildDockercontainer(itwilltakesometime)$dockerbuild-tiac-scan-runner.#runIaCScanRunnerRESTAPIinaDockercontainerand#navigatetolocalhost:8080/swaggerorlocalhost:8080/redoc$dockerrun--nameiac-scan-runner-p8080:80iac-scan-runnerRun from CLITo run using the IaC Scan Runner CLI:#installtheCLI$python3-mvenv.venv&&..venv/bin/activate(.venv)$pipinstalliac-scan-runner#printOpenAPIspecification(.venv)$iac-scan-runneropenapi#installprerequisites(.venv)$iac-scan-runnerinstall#runIaCScanRunnerRESTAPI(.venv)$iac-scan-runnerrunRun from sourceTo run locally from source:#Exportenvvariablesexport MONGODB_CONNECTION_STRING=mongodb://localhost:27017export SCAN_PERSISTENCE=enabledexport USER_MANAGEMENT=enabled#SetupMongoDB$dockerrun--namemongodb-p27017:27017mongo#installprerequisites$python3-mvenv.venv&&..venv/bin/activate(.venv)$pipinstall-rrequirements.txt(.venv)$./install-checks.sh#runIaCScanRunnerRESTAPI(add--reloadflagtoapplycodechangesontheway)(.venv)$uvicornsrc.iac_scan_runner.api:appUsage and examplesThis part will show one of the possible deployments and short examples on how to use API calls.Firstly we will clone theiac scan runnerrepository and run the API.$gitclonehttps://github.com/xlab-si/iac-scan-runner.git$dockercomposeupAfter this is done you can use different API endpoints by calling localhost:8000.
You can also navigate to localhost:8000/swagger or localhost:8000/redoc and test all the API endpoints there.
In this example, we will use curl for calling API endpoints.Lets create a project named test.curl -X 'POST' \'http://0.0.0.0/project?creator_id=test' \-H 'accept: application/json' \-d ''project id will be returned to us. For this example project id is 1e7b2a91-2896-40fd-8d53-83db56088026.For example, let say we want to initiate all check expect ansible-lint. Let's disable it.curl -X 'PUT' \'http://0.0.0.0:8000/projects/1e7b2a91-2896-40fd-8d53-83db56088026/checks/ansible-lint/disable' \-H 'accept: application/json'Now when project is configured, we can simply choose files that we want to scan and zip them. For IaC-Scan-Runner to
work files are expected to be a compressed archives (usually zip files). In this case response type will be json
, but it is possible to change it to html.Please change YOUR.zip to path of your file.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 'iac=@YOUR.zip;type=application/zip'That is it.Extending the scan workflow with new check toolsAt certain point, it might be required to include new check tools within the scan workflow, with aim to provide wider coverage of IaC standards and project types. Therefore, in this subsection, a sequence of required steps for that purpose is identified and described. However, the steps have to be performed manually as it will be described, but it is planned to automatize this procedure in future via API and provide user-friendly interface that will aid the user while importing new tools that will become part of the available catalogue that makes the scan workflow.  Figure 16 depicts the required steps which have to be taken in order to extend the scan workflow with a new tool.Step 1 – Adding tool-specific class to checks directory
First, it is required to add a new tool-specific Python class to the checks directory inside IaC Scan Runner’s source code:
iac-scan-runner/src/iac_scan_runner/checks/new_tool.pyThe class of a new tool inherits the existing Check class, which provides generalization of scan workflow tools. Moreover, it is necessary to provide implementation of the following methods:def configure(self, config_filename: Optional[str], secret: Optional[SecretStr])def run(self, directory: str)
While the first one aims to provide the necessary tool-specific parameters in order to set it up (such as passwords, client ids and tokens), another one specifies how the tool itself is invoked via API or CLI and its raw output returned.Step 2 – Adding the check tool class instance within ScanRunner constructor
Once the new class derived from Check is added to the IaC Scan Runner’s source code, it is also required to modify the source code of its main class, called ScanRunner. When it comes to modifications of this class, it is required first to import the tool-specific class, create a new check tool-specific class instance and adding it to the dictionary of IaC checks inside def init_checks(self).
A.	Importing the check tool class
from iac_scan_runner.checks.tfsec import TfsecCheck
B.	Creating new instance of check tool object inside init_checks
"""Initiate predefined check objects"""
new_tool = NewToolCheck()
C.	Adding it to self.iac_checks dictionary inside init_checksself.iac_checks = {new_tool.name: new_tool,…}Step 3 – Adding the check tool to the compatibility matrix inside Compatibility class
On the other side, inside file src/iac_scan_runner/compatibility.py, the dictionary which represents compatibility matrix should be extended as well. There are two possible cases: a) new file type should be added as a key, together with list of relevant tools as value b) new tool should be added to the compatibility list for the existing file type.compatibility_matrix = {"new_type": ["new_tool_1", "new_tool_2"],…"old_typeK": ["tool_1", …  "tool_N", "new_tool_3"]}Step 4 – Providing the support for result summarization
Finally, the last step in sequence of required modifications for scan workflow extension is to modify class ResultsSummary (src/iac_scan_runner/results_summary.py). Precisely, it is required to append a part of the code to its method summarize_outcome that will look for specific strings which are tool-specific and can be used to identify whether the check passed or failed. Inside the loop that traverses the compatible checks, for each new tool the following structure of if-else should be included: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"LicenseThis work is licensed under theApache License 2.0.ContactYou can contact the xOpera team by sending an email toxopera@xlab.si.AcknowledgementThis project has received funding from the European Union’s Horizon 2020 research and innovation programme under Grant
Agreement No. 101000162 (PIACERE).