# Insights CLI
# About
The Fairwinds Insights Command-Line Interface (opens new window) (CLI) is a command-line tool for interacting with the Fairwinds Insights API. In particular, it makes it easy to manage Insights Policies and Automation Rules as code and validate OPA policies offline.
# Installation
# Homebrew Tap
brew install FairwindsOps/tap/insights
# Binary
Install the binary from our releases (opens new window) page.
# Setup
To start using the Insights CLI, you'll need to retrieve your admin token
from your organization's Settings
page at insights.fairwinds.com
.
Set that token in your environment with:
export FAIRWINDS_TOKEN=$YOUR_ADMIN_TOKEN
# fairwinds-insights.yaml
You can set up a YAML file containing details for the CLI, including your organization name and hostname (required for self hosted deployments):
options:
organization: acme-co
hostname: https://insights.example.com
By default, the CLI will look for the file fairwinds-insights.yaml
in the current directory, but its
location can be configured by passing in the --config <filename>
flag.
If the fairwinds-insights.yaml
file does not exist, the --organization
flag must be used when running the CLI,
passing in the name of your organization.
# Syncing
# Policy Configuration
You can use the Insights CLI to manage the configuration of Policies.
Check out the Policy Configuration documentation on use cases for configuring Policies.
insights-cli push settings
# Custom OPA Policies
When pushing OPA policies to Insights, the CLI expects a directory structure like the following:
.
+-- opa
| +-- policy-name
| +-- policy.rego
| +-- second-policy-name
| +-- policy.rego
The Policy file name must be policy.rego
.
Once the files have been created, use the following command to push the OPA policies to Insights:
insights-cli push opa
# Deleting OPA Policies From Insights
By default, the Insights CLI will not delete any OPA policies from Insights. It will only add or update them. This means there might be some OPA policies running in Insights that are not tracked in your Infrastructure-as-Code (IaC) repository.
You can add the --delete
flag to the push opa
command, which
will delete any OPA policies from Insights that do not exist in your IaC repository. Adding the --dry-run
flag will explain which Policies would be deleted without making changes to Insights.
# Automation Rules
When pushing Automation Rules to Insights, the CLI expects a directory structure like the following:
.
+-- rules
| +-- rule-name.yaml
| +-- second-rule-name.yaml
The file names must have a .yaml
extension.
Once the files have been created, use the following command to push the Rules to Insights
insights-cli push rules
# Example
To upload an Automation Rule to Insights, create the file rules/api-action-items.yaml
in the rules
sub-directory:
name: "Assign API Action Items"
description: "Assigns all Action Items in the api namespace to [email protected]"
action: |
if (ActionItem.ResourceNamespace === 'api') {
ActionItem.AssigneeEmail = '[email protected]';
}
# Automation Rule Metadata Fields
The following metadata fields can be specified in the Rule file:
name
- the name of the Automation Rule in Insightsdescription
- the description of the Automation Rule in Insightscontext
- specifyAgent
,CI/CD
, orAdmissionController
(leave blank to specify all options)cluster
- the name of a specific cluster this Rule should apply torepository
- the name of a specific repository this Rule should apply toreportType
- the type of report (e.g.polaris
,trivy
, etc.) this Rule should apply to
# Deleting Automation Rules From Insights
By default, the Insights CLI will not delete any automation rules from Insights. It will only add or update them. This means there might be some Automation Rules running in Insights that are not tracked in your Infrastructure-as-Code (IaC) repository.
You can add the --delete
flag to the push rules
command, which
will delete any Automation Rules from Insights that do not exist in your IaC repository. Adding the --dry-run
flag will explain which Rules would be deleted without making changes to Insights.
# Testing
You can use the insights-cli to test your OPA policies and automation rules. This can also be integrated into the CI/CD pipeline for the Infrastructure-as-Code repo containing your Insights configuraiton.
# Custom OPA Policies
The Insights CLI can validate OPA policies which is useful for local policy development or in your CI/CD workflow. Validation includes:
- Verifying rego syntax - the query language used by OPA policies
- Verifying Insights provided functions, such as
kubernetes()
andinsightsinfo()
, have the correct number of parameters - Displaying optional rego
print
statements to aide in debugging - Showing Policy output, and verifying the syntax of any Insights Action Item
- Require the OPA policy to succeed or fail in order to pass validation. Configurable via a command-line flag or the extension of the Kubernetes manifest yaml file name
The insights-cli validate opa
command requires an OPA policy file, and a Kubernetes manifest file that will be passed as input to the Policy:
insights-cli validate opa -r not-in-namespace/policy.rego -k test-pod.yaml
Run insights-cli validate opa --help
for more options when validating Policies.
# Requiring Policy Success or Failure
The --expect-action-item
command-line flag configures whether validation expects a policy to output an Insights Action Item. By default, policies are expected to generate a single Action Item to be considered valid. Setting --expect-action-item=false
expects Kubernetes manifest files to cause the OPA policy to not output an Action Item.
Alternatively, the extension of the Kubernetes manifest file will determine whether that Policy is expected to produce an Action Item:
.success.yaml
- the OPA policy is not expected to output an Action Item.failure.yaml
- the OPA policy is expected to output an Action Item- Any other
*.yaml
- the expectation is configured by the--expect-action-item
command-line flag
When validating OPA policies in batch mode, each Policy can have a mix of the above Kubernetes yaml files, all of which will be used for validation. For example:
.
+-- file.rego
+-- file.yaml
+-- another-policy.rego
+-- another-policy.success.yaml
+-- another-policy.failure.yaml
+-- another-policy.yaml
# Batch Validation of OPA Policies for CI/CD
The --batch-dir
option instructs the insights-cli validate opa
command to process all .rego
files in the specified directory.
When validating Policies using this option, the command expects the following directory structure:
.
+-- file.rego
+-- file.yaml
+-- another-policy.rego
+-- another-policy.yaml
The name of the .rego
and .yaml
files must match.
Next use the Insights CLI to validate all OPA policies
insights-cli validate opa --batch-directory <directory_path>
# Automation Rules
Before pushing Automation Rules to Insights, you can use the CLI to check if the results will work as expected. For the testing, you will need to create a rule file and action item file. You also have the option to create an expected output file to compare to the actual result.
Rule file example, default file name is ./rule.js:
if (ActionItem.ReportType === "trivy" && ActionItem.Cluster === "production") {
ActionItem.Severity = 0.9;
}
Action item file example, default file name is ./action-item.yaml:
title: Image has vulnerabilities
cluster: production
severity: 0.1
Expected output Action item file example:
title: Image has vulnerabilities
cluster: production
severity: 0.9
Once the files have been created, use the following command to validate the rule against Insights:
insights-cli validate rule --insights-context <insights context> --report-type <report type> {--automation-rule-file <rule file> --action-item-file <action item file>} [--expected-action-item <expected output file>]
Example:
insights-cli validate rule --insights-context Agent --report-type trivy --automation-rule-file ./rule.js --action-item-file ./action-items.yaml --expected-action-item ./expected-output.yaml
If the expected output is provided and the actual result matches, a success message is displayed:
INFO Success - actual response matches expected response
If no expected output is provided the updated action item yaml is displayed:
title: Image has vulnerabilities
cluster: production
severity: 0.9
# Verifying an Automation Rule
Once you've uploaded an Automation Rule, it will be triggered the next time the Insights Agent, CI process or Admission Controller runs.
To be sure the Rule functions correctly, you can manually trigger the Agent by running:
kubectl create job rule-test --from cronjob/$REPORT -n insights-agent
Where $REPORT is polaris
, trivy
or any other report type you'd like to test.