CLI Tool Commands and Parameters - Terraform and CloudFormation

After you have setup the command line interface (CLI) Infrastructure as Code (IaC) scanning tool via Docker or local executable, you're ready to start using it with Terraform and/or AWS CloudFormation Template (CFT) infrastructure. If you have questions or issues, reach out to us using the Customer Support Portal. If you're looking to use IaC with Terraform Cloud/Enterprise instead, see Integrate with Terraform Cloud/Enterprise (TFC/E) for more information.

Prerequisites

Before scanning Terraform or CFT files with the scanning tool, ensure you have the following:

Rename Executable

When you download the mimics executable initially, the file name will be suffixed with the version and architecture. We recommend renaming the executable to mimics (for Mac/Linux) or mimics.exe (for Windows) for ease of use. The examples in our docs use a simplified executable name.

If you have questions or issues, reach out to us using the Customer Support Portal.

Command List & Parameters

The command list and parameters are the same regardless if you're using mimics via local executable or Docker.

Global Flags and Parameters

NameTypeDescription
--api-keystringInsightCloudSec API Key
Note: If using the Docker version of the CLI, this is better passed as a Docker environment variable. Review the Docker Examples for more information
--base-urlstringInsightCloudSec base URL, including protocol (e.g., http://localhost:8080/)

Note: If using the Docker version of the CLI, this is better passed as a Docker environment variable. Review the Docker Examples for more information
--ca-certificatestringSets the trusted authorities for SSL verification using a CA bundle file (.pem) (supersedes --no-verify)
--config-filestringConfiguration file location (default: .mimics.yaml or $HOME/.mimics.yaml)
-h, --helpN/ADisplays the help menu. Contextual help for each command is also available in the following formats: ./mimics help [command] or ./mimics [command] [-h|--help]

Because each command may have sub-commands, the help menu is also available in this format: ./mimics [command] [sub-command] [-h|--help]
--no-colorN/ADisables color output
--no-verifyN/ADisables SSL verification for all API calls to InsightCloudSec. This is superseded by the usage of --ca-certificate
--log-formatstringSets the log format. Options: "text", "json" (default: "text")
--log-levelstringSets the log level. Options: "trace", "debug", "info", "warn", "error", "fatal" (default: "info")
--log-pathstringSets the log file path (default: "./log/mimics.log")

Commands

NameDescriptionSub-Commands
ics-configList and view InsightCloudSec IAC configurations- list -- List scan configurations
- show <config-name> -- Detail a given scan configuration
helpDisplays the help menu for a given command, e.g., ./mimics help [command]N/A
scanScans IaC files. This command is always paired with IaC file(s) to scan, e.g., ./mimics scan file-name.json [flags and parameters] or ./mimics scan ./path/to/files [flags and parameters]See Flags and Parameters for <code>scan</code> for more information
parseParse IaC files into their mimics-internal representation, e.g., ./mimics parse file-name.jsonN/A
versionDisplays the mimics versionN/A

Flags and Parameters for <code>scan</code>

NameTypeDescription
--concurrent-filesintNumber of files to scan concurrently (default: 10)
--custom-insights-pathstringExperimental: Path to a directory of custom Rego Insights
--disable-remoteN/ADisables remote scanning
-c, --ics-configstringName of the InsightCloudSec IaC configuration to use
--no-failN/ASuppresses error code returned by scans containing failures
--overrides-pathstringPath to a JSON file. Defaults to none.
- CFT only. Takes a JSON file to specify values for pseudo-parameters and to override values for user-defined parameters. These values take precedent over those specified via --parameters-path
- See the parameters and pseudo-parameters documentation for a detailed setup guide. This file should be formatted as a JSON object with pseudo-parameter/parameter names as keys
--parameters-pathstringPath to a CloudFormation Template (CFT) parameters file. Defaults to none.
- CFT only. Takes a JSON file to specify values for any user-defined parameters
- See the parameters and pseudo-parameters documentation for a detailed setup guide. The existing parameter JSON file that you would normally pass to AWS using aws cloudformation create-stack --parameters is supported
--report-formatsstringFormat of scan result report artifacts (options: all, sarif, html, junitxml). If not provided, no artifacts will be saved
--report-namestringName used for generated report artifact files (default: "ics_scan")
--report-pathstringDirectory path to store report artifacts. Defaults to the current directory
--save-reportN/ASave the scan report to InsightCloudSec (when not using an existing InsightCloudSec IaC configuration)
-t, --scan-targetstringOverrides the default scan target. Defaults to <hostname>:<number of files>:<file names>
--scan-timeoutintDuration in seconds before processing an individual file should timeout. Default is 60 (0 = never)
--show-exceptionsN/AShow excepted findings in results

Using <code>mimics</code> with Terraform/CFT

Use of the scanning tool depends on how you set it up. Below are examples using the scanning tool with each setup method.

Docker

Because the scanning tool is invoked using a public Docker image, the base command is more complicated than invoking the local executable:

bash
1
docker run [docker flags] public.ecr.aws/rapid7-insightcloudsec/ics/mimics:latest [mimics command] [mimics flags]

Important Docker Flags

InsightCloudSec recommends providing the following Docker flags with each invocation:

  • Use -v to establish a local volume that the Docker container can pull files from
  • Use -e to establish an environment variable the Docker container recognizes -- two variables will need to be passed into the image: InsightCloudSec URL and API Key

Scan Example

bash
1
# Generate a Terraform plan and convert it to JSON
2
terraform plan -out tf.plan
3
terraform show -json tf.plan > plan.json
4
5
# Run our IaC tool via docker
6
docker run \
7
-v $(pwd):/data \
8
-e MIMICS_BASE_URL=$ICS_BASE_URL \
9
-e MIMICS_API_KEY=$ICS_API_KEY \
10
public.ecr.aws/rapid7-insightcloudsec/ics/mimics:latest scan \
11
data/plan.json \
12
-c "Azure Checks" \
13
--report-formats all \
14
--report-path "data/reports" \
15
--no-progress

List IaC Configurations Example

bash
1
docker run
2
-v $(pwd):/data \
3
-e MIMICS_BASE_URL=$ICS_BASE_URL \
4
-e MIMICS_API_KEY=$ICS_API_KEY \
5
public.ecr.aws/rapid7-insightcloudsec/ics/mimics:latest ics-config list \
6
--no-verify
7
Config name | Total scans | Last scan time
8
----------- | ----------- | --------------
9
tests config1 | 132 | 2022-05-21T10:43:46Z
10
AWS Config | 3 | 2021-04-09T13:07:50ZZ
11
test config 4 | 1 | 2019-11-15T15:20:24Z
12
HIPAA Custom | 4 | 2020-07-08T19:55:10Z

Local Executable

To actually use the local executable, follow the pattern ./mimics [command] [flags] for Mac or mimic.exe [command] [flags] for Windows.

Scan Example

bash
1
# Generate a Terraform plan and convert it to JSON
2
terraform plan -out tf.plan
3
terraform show -json tf.plan > plan.json
4
5
./mimics scan plan.json \
6
-c "Azure Checks" \
7
--report-formats all \
8
--report-path "data/reports" \
9
--no-progress \
10
--api-key "<my-api-key>" \
11
--base-url "http://localhost:8001/" \
12
--no-verify

Show IaC Configuration Example

bash
1
./mimics ics-config show "tests config1" \
2
--api-key "<my-api-key>" \
3
--base-url "http://localhost:8001/" \
4
--no-verify
5
Insight Name | Description
6
------------ | -----------
7
Cloud Account without Global API Accounting Config (AWS) | Identify Accounts Without API Accounting Config, Such as AWS CloudTra...
8
Cloud Root Account API Access Key Present | Identify Accounts With API Access Keys Present on the Root Account
9
Cloud User Account without MFA | Identify cloud user accounts which do not require two-factor authenti...
10
Cloud Account without Root Account MFA Protection | Identify Accounts Which Still Have the Root Account Active Without Tw...
11
Network without Traffic Logging | Identify Networks, e.g., AWS VPCs, That Do Not Have Network Logging E...
12
API Key Unused For 90 Days | Identify API keys that have not been used within the past 90 days

Viewing CLI Scan Details in the UI

After performing a scan using the CLI tool you can view scan details through the InsightCloudSec UI. All CLI Scans will be included in the IaC Scan list and can be viewed in the same way as other scans.

Check out the Viewing Scan Results page for details on viewing your scan results within the UI, including summary details.