Documentation / Tools and Integrations

Run your test

Run your first compliance test

This walkthrough creates an end-to-end compliance test against a Git repository: a container, a connector, a snapshot and a compliance file. Once uploaded, you run the compliance and a report is produced.

Before you start

A Prancer collection (container) you can upload files into — see Collection.
A Git repository that holds the IaC template you want to validate (the example uses prancer-tests).
Familiarity with Connector, Snapshot and Compliance concepts.

Step 1 — Create the container

Create a container named git_container. The full procedure is in Collection. The new container appears in the container list.

Step 2 — Upload the connector

The connector tells Prancer how to reach the data source. For a Git source, set type: filesystem and fileType: structure.

git_connector.json:

{
    "fileType": "structure",
    "type": "filesystem",
    "companyName": "prancer-test",
    "gitProvider": "https://github.com/prancer-io/prancer-tests",
    "branchName": "master",
    "httpsUser": null,
    "httpsPassword": null,
    "sshKeyfile": null,
    "private": false,
    "sshUser": "git"
}

Upload it via the Connector page.

Step 3 — Upload the snapshot

The snapshot defines the individual resources to evaluate. Set fileType: snapshot, type: git, and point source at the connector you just uploaded.

git_snapshot.json:

{
    "fileType": "snapshot",
    "snapshots": [
        {
            "source": "git_connector",
            "testUser": "git",
            "branchName": "master",
            "type": "git",
            "nodes": [
                {
                    "snapshotId": "1",
                    "type": "json",
                    "collection": "security_groups",
                    "path": "devops/cf/mytemplate.json",
                    "status": "active"
                }
            ]
        }
    ]
}

Upload it via the Snapshot page.

Step 4 — Upload the compliance file

Compliance cases reference snapshots by their snapshotId. In the example below, {1} resolves to the snapshot with snapshotId: "1" from step 3.

git_test.json:

{
    "fileType": "test",
    "snapshot": "git_snapshot",
    "testSet": [
        {
            "testName": "Ensure port 80 and 443 rules exists",
            "version": "0.1",
            "cases": [
                {
                    "testId": "1",
                    "rule": "exist({1}.Resources.PrancerTutorialSecGroup.Properties.SecurityGroupIngress['FromPort'=80])",
                    "title": "Security Group Ingress should contain port 80",
                    "description": "If port 80 exists in properties, the test passes.",
                    "tags": [{ "cloud": "git", "compliance": ["CUSTOM"], "service": [] }]
                },
                {
                    "testId": "2",
                    "rule": "exist({1}.Resources.PrancerTutorialSecGroup.Properties.SecurityGroupIngress['FromPort'=443])",
                    "title": "Security Group Ingress should contain port 443",
                    "description": "If port 443 exists in properties, the test passes.",
                    "tags": [{ "cloud": "git", "compliance": ["CUSTOM"], "service": [] }]
                }
            ]
        },
        {
            "testName": "Ensure port 22 rule exists and is only open to internal",
            "version": "0.1",
            "cases": [
                {
                    "testId": "3",
                    "rule": "exist({1}.Resources.PrancerTutorialSecGroup.Properties.SecurityGroupIngress[])",
                    "title": "SecurityGroupIngress is present",
                    "description": "If SecurityGroupIngress exists, the test passes.",
                    "tags": [{ "cloud": "git", "compliance": ["CUSTOM"], "service": [] }]
                },
                {
                    "testId": "4",
                    "rule": "{1}.Resources.PrancerTutorialSecGroup.Properties.SecurityGroupIngress['FromPort'='22'].CidrIp='172.16.0.0/16'",
                    "title": "Port 22 restricted to 172.16.0.0/16",
                    "description": "Pass if SecurityGroupIngress for port 22 has CidrIp 172.16.0.0/16.",
                    "tags": [{ "cloud": "git", "compliance": ["CUSTOM"], "service": [] }]
                },
                {
                    "testId": "5",
                    "rule": "{1}.Resources.PrancerTutorialSecGroup.Properties.SecurityGroupIngress['FromPort'='22'].CidrIp='172.16.0.0/24'",
                    "title": "Port 22 restricted to 172.16.0.0/24",
                    "description": "Pass if SecurityGroupIngress for port 22 has CidrIp 172.16.0.0/24.",
                    "tags": [{ "cloud": "git", "compliance": ["CUSTOM"], "service": [] }]
                }
            ]
        }
    ]
}

Upload it via the Compliance page.

Tip: Snapshot IDs are interpreted as positional placeholders inside rule expressions. {1} always refers to snapshotId: "1" of the named snapshot file.

Step 5 — Run the compliance

Trigger the run from the Run Compliance page. When it finishes, a report is generated showing each test case as Pass or Fail.