OpenClarity

https://openclarity.io/docs/
Admin
OpenClarity is an open source tool for agentless detection and management of Virtual Machine...
Tokens:9,793
Snippets:171
Trust Score:6.3
Update:6 months ago
Show doc for...
Tokens:
Raw
### Docker Compose Up Output Example

Source: https://openclarity.io/docs/getting-started/deploy-docker

This is an example of the expected output when OpenClarity services are successfully started using Docker Compose. It shows the status of networks, volumes, and containers.

```text
[+] Running 14/14
⠿ Network openclarity                        Created                                                       0.2s
⠿ Volume "openclarity_grype-server-db"       Created                                                       0.0s
⠿ Volume "openclarity_apiserver-db-data"     Created                                                       0.0s
⠿ Container openclarity-orchestrator-1       Healthy                                                      69.7s
⠿ Container openclarity-yara-rule-server-1   Healthy                                                      17.6s
⠿ Container openclarity-exploit-db-server-1  Healthy                                                      17.7s
⠿ Container openclarity-swagger-ui-1         Healthy                                                       7.8s
⠿ Container openclarity-trivy-server-1       Healthy                                                      26.7s
⠿ Container openclarity-uibackend-1          Healthy                                                      17.6s
⠿ Container openclarity-ui-1                 Healthy                                                       7.7s
⠿ Container openclarity-freshclam-mirror-1   Healthy                                                       7.8s
⠿ Container openclarity-grype-server-1       Healthy                                                      37.3s
⠿ Container openclarity-gateway-1            Healthy                                                       7.7s
⠿ Container openclarity-apiserver-1          Healthy                                                      17.7s

```

--------------------------------

### Initialize Configuration File

Source: https://openclarity.io/docs/getting-started/deploy-gcp

Copies the example configuration file to the required filename.

```bash
cp openclarity-config.example.yaml openclarity-config.yaml
```

--------------------------------

### Start OpenClarity Services with Docker Compose

Source: https://openclarity.io/docs/getting-started/deploy-docker

This command initiates all OpenClarity control plane elements using Docker Compose. The --wait flag ensures services are healthy before proceeding. Use --remove-orphans to clean up any dangling containers.

```bash
docker compose --project-name openclarity --file docker-compose.yml up -d --wait --remove-orphans
```

--------------------------------

### Install OpenClarity via Helm

Source: https://openclarity.io/docs/getting-started/deploy-kubernetes

Deploys OpenClarity version 1.1.2 into the openclarity namespace.

```bash
helm install openclarity oci://ghcr.io/openclarity/charts/openclarity --version 1.1.2 \
    --namespace openclarity --create-namespace \
    --set orchestrator.provider=kubernetes \
    --set orchestrator.serviceAccount.automountServiceAccountToken=true
```

--------------------------------

### GET /assets

Source: https://openclarity.io/docs/api

Retrieves a list of all assets managed by the system.

```APIDOC
## GET /assets

### Description
Get all assets currently registered in the system.

### Method
GET

### Endpoint
/assets
```

--------------------------------

### Run OpenClarity Stack with Docker

Source: https://openclarity.io/docs/contributing

Start the OpenClarity stack locally using Docker Compose with specific environment overrides.

```bash
docker compose --project-name openclarity \
               --file installation/docker/docker-compose.yml \
               --env-file installation/docker/image_override.env \
               up -d --wait --remove-orphans
```

--------------------------------

### Configure KICS Scanner Plugin

Source: https://openclarity.io/docs/features/plugins

Example configuration for the `.families.yaml` file to enable and configure the KICS scanner for IaC misconfigurations. Ensure the KICS scanner image is correctly specified.

```yaml
# --- .families.yaml
plugins:
  enabled: true
  scanners_list:
    - "kics"
  inputs: 
    - input: "/tmp"
      input_type: "rootfs"
  scanners_config:
    kics:
      image_name: "ghcr.io/openclarity/openclarity-plugin-kics:latest"
      config: "{}"

```

--------------------------------

### Download OpenClarity Release

Source: https://openclarity.io/docs/getting-started/deploy-docker

Use this command to download the latest OpenClarity release archive. Ensure you have wget installed.

```bash
wget https://github.com/openclarity/openclarity/releases/download/v1.1.2/docker-compose-v1.1.2.tar.gz
```

--------------------------------

### GET /scans

Source: https://openclarity.io/docs/api

Retrieves all multi-asset scheduled scans.

```APIDOC
## GET /scans

### Description
Get all scans. Each scan contains details about a multi-asset scheduled scan.

### Method
GET

### Endpoint
/scans
```

--------------------------------

### GET /assets/{assetID}

Source: https://openclarity.io/docs/api

Retrieves details for a specific asset by its ID.

```APIDOC
## GET /assets/{assetID}

### Description
Get details for a specific asset.

### Method
GET

### Endpoint
/assets/{assetID}

### Parameters
#### Path Parameters
- **assetID** (string) - Required - The unique identifier of the asset.
```

--------------------------------

### Check Cloud-Init Logs

Source: https://openclarity.io/docs/troubleshooting

After establishing SSH access, check the cloud-init logs to debug the VM's start-up configuration. This command is run with superuser privileges.

```bash
sudo journalctl -u cloud-final
```

--------------------------------

### Extract and Navigate to Docker Compose Directory

Source: https://openclarity.io/docs/getting-started/deploy-docker

Create a directory, extract the downloaded archive into it, and then change into that directory. This prepares your environment for Docker Compose.

```bash
mkdir docker-compose-v1.1.2
tar -xvzf docker-compose-v1.1.2.tar.gz -C docker-compose-v1.1.2
cd docker-compose-v1.1.2
```

--------------------------------

### Create a Kubernetes cluster with Kind

Source: https://openclarity.io/docs/getting-started/deploy-kubernetes

Initializes a local Kubernetes cluster named openclarity-k8s.

```bash
kind create cluster --name openclarity-k8s
```

--------------------------------

### Initiate Scan and Report to File

Source: https://openclarity.io/docs/usage/command_line

Use this command to initiate a scan and save the results to a specified output file.

```bash
./bin/openclarity-cli scan --config ~/testConf.yaml -o outputfile
```

--------------------------------

### Configure and Run OpenClarity CLI Scan

Source: https://openclarity.io/docs/concepts/sbom/output-sbom-format

Create a configuration file specifying the SBOM output format and execute the scan command.

```bash
# Create config based on https://github.com/openclarity/openclarity/blob/main/.families.yaml
cat <<EOF > config.yml
sbom:
  enabled: true
  analyzers_list:
    - "syft"
  inputs:
    - input: "/dir-to-scan"
      input_type: "rootfs"
  output_format: "cyclonedx-json"
EOF

# Run scan
openclarity-cli scan --config config.yml
```

--------------------------------

### Build and Publish OpenClarity Containers

Source: https://openclarity.io/docs/contributing

Use 'make docker' to build all OpenClarity containers. Set 'DOCKER_PUSH=true' to publish them to a registry. Override the destination registry with 'DOCKER_REGISTRY'. Ensure you are logged into your Docker registry locally.

```bash
DOCKER_REGISTRY=docker.io/my-openclarity-images DOCKER_PUSH=true make docker

```

--------------------------------

### Deploy via Deployment Manager

Source: https://openclarity.io/docs/getting-started/deploy-gcp

Executes the deployment using the gcloud deployment-manager with the provided configuration file.

```bash
gcloud deployment-manager deployments create <openclarity deployment name> --config openclarity-config.yaml
```

--------------------------------

### Extract Deployment Files

Source: https://openclarity.io/docs/getting-started/deploy-gcp

Creates a directory and extracts the downloaded tarball into it.

```bash
mkdir gcp-deployment-v1.1.2
tar -xvzf gcp-deployment-v1.1.2.tar.gz -C gcp-deployment-v1.1.2
cd gcp-deployment-v1.1.2
```

--------------------------------

### Configure Go Workspace

Source: https://openclarity.io/docs/contributing

Use a go.work file to ensure the gopls language server correctly resolves references across the project modules.

```go
go 1.22.6

use (
  ./api/client
  ./api/server
  ./api/types
  ./cli
  ./containerruntimediscovery/client
  ./containerruntimediscovery/server
  ./containerruntimediscovery/types
  ./core
  ./e2e
  ./e2e/testdata
  ./installation
  ./orchestrator
  ./provider
  ./plugins/runner
  ./plugins/sdk-go
  ./plugins/sdk-go/example
  ./plugins/store/kics
  ./scanner
  ./testenv
  ./uibackend/client
  ./uibackend/server
  ./uibackend/types
  ./utils
  ./workflow
)
```

--------------------------------

### POST /assets

Source: https://openclarity.io/docs/api

Creates a new asset in the system.

```APIDOC
## POST /assets

### Description
Create a new asset.

### Method
POST

### Endpoint
/assets
```

--------------------------------

### SSH into Scanner VM via OpenClarity Server

Source: https://openclarity.io/docs/troubleshooting

Use this command to establish an SSH connection to a Scanner VM on cloud providers. The OpenClarity server acts as a bastion host. Ensure you have the correct key-pair private key and IP addresses.

```bash
ssh -i <key-pair private key> -J ubuntu@<openclarity server public IP> ubuntu@<scanner VM private IP address>
```

--------------------------------

### Create a ScanEstimation resource

Source: https://openclarity.io/docs/features/cost-estimation

Submit a POST request with this JSON body to initiate a cost estimation for a specific workload.

```json
{
  "assetIDs": ["i-123456789"],
  "state": {
    "state": "Pending"
  },
  "scanTemplate": {
    "scope": "contains(assetInfo.tags, '{\"key\":\"scanestimation\",\"value\":\"test\"}')",
    "assetScanTemplate": {
      "scanFamiliesConfig": {
        "sbom": {
          "enabled": true
        }
      }
    }
  }
}
```

--------------------------------

### Run Go Unit Tests for a Specific Package

Source: https://openclarity.io/docs/contributing

Execute Go unit tests for a specific package or test using the standard Go test CLI. This command targets tests within the './cli/cmd/...' path, specifically looking for tests matching 'Test_isSupportedFS'.

```go
go test ./cli/cmd/... -run Test_isSupportedFS

```

--------------------------------

### Extract CloudFormation Files

Source: https://openclarity.io/docs/getting-started/deploy-aws

Create a directory and extract the contents of the downloaded AWS CloudFormation archive into it. This prepares the template files for deployment.

```bash
mkdir aws-cloudformation-v1.1.2
tar -xvzf aws-cloudformation-v1.1.2.tar.gz -C aws-cloudformation-v1.1.2

```

--------------------------------

### Configure KICS scanner via .families.yaml

Source: https://openclarity.io/docs/concepts/plugins

Use this configuration file with the OpenClarity CLI scan command to enable the KICS scanner for IaC security misconfigurations.

```yaml
# --- .families.yaml
plugins:
  enabled: true
  scanners_list:
    - "kics"
  inputs: 
    - input: "/tmp"
      input_type: "rootfs"
  scanners_config:
    kics:
      image_name: "ghcr.io/openclarity/openclarity-plugin-kics:latest"
      config: "{}"
```

--------------------------------

### POST /scans

Source: https://openclarity.io/docs/api

Creates a new multi-asset scheduled scan.

```APIDOC
## POST /scans

### Description
Create a multi-asset scheduled scan.

### Method
POST

### Endpoint
/scans
```

--------------------------------

### Verify OpenClarity pod deployment

Source: https://openclarity.io/docs/getting-started/deploy-kubernetes

Checks the status of pods within the openclarity namespace.

```bash
kubectl get pods -n openclarity
```

--------------------------------

### Check OpenClarity Scanner Service Logs

Source: https://openclarity.io/docs/troubleshooting

View the logs for the OpenClarity scanner service to diagnose issues. This command requires superuser privileges.

```bash
sudo journalctl -u openclarity-scanner
```

--------------------------------

### Download OpenClarity Release Archive

Source: https://openclarity.io/docs/getting-started/deploy-aws

Use wget to download the OpenClarity AWS CloudFormation release archive. Ensure you are downloading the correct version.

```bash
wget https://github.com/openclarity/openclarity/releases/download/v1.1.2/aws-cloudformation-v1.1.2.tar.gz

```

--------------------------------

### Establish SSH Tunnel

Source: https://openclarity.io/docs/getting-started/deploy-gcp

Creates an SSH tunnel to the OpenClarity server to access the UI locally.

```bash
gcloud compute ssh --project=<project id> --zone=<zone name> <name of your VM> -- -NL 8080:localhost:80
```

--------------------------------

### Configure VSCode for JavaScript/React Formatting

Source: https://openclarity.io/docs/contributing

Configure VSCode's settings.json to enable auto-formatting for JavaScript and React files using Prettier. This ensures consistent code style within the 'ui/' directory.

```json
{
  "[javascriptreact]": {
    "editor.formatOnSave": true,
    "editor.formatOnType": true,
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  ...
}

```

--------------------------------

### Download OpenClarity GCP Release

Source: https://openclarity.io/docs/getting-started/deploy-gcp

Downloads the specified version of the OpenClarity GCP deployment package from GitHub.

```bash
wget https://github.com/openclarity/openclarity/releases/download/v1.1.2/gcp-deployment-v1.1.2.tar.gz
```

--------------------------------

### Verify Kubernetes cluster status

Source: https://openclarity.io/docs/getting-started/deploy-kubernetes

Lists active Kind clusters to ensure the environment is ready.

```bash
kind get clusters
```

--------------------------------

### One-Liner to Report Scan Results to OpenClarity Backend

Source: https://openclarity.io/docs/usage/command_line

This one-liner combines asset creation, asset scan creation, and the scan initiation into a single command for reporting results to the OpenClarity backend.

```bash
./bin/openclarity-cli asset-create --file docs/assets/dir-asset.json --server http://localhost:8080/api --update-if-exists --jsonpath {.id} | xargs -I{} ./bin/openclarity-cli asset-scan-create --asset-id {} --server http://localhost:8080/api --jsonpath {.id} | xargs -I{} ./bin/openclarity-cli scan --config ~/testConf.yaml --server http://localhost:8080/api --asset-scan-id {}
```

--------------------------------

### Establish SSH Tunnel to OpenClarity Server

Source: https://openclarity.io/docs/getting-started/deploy-aws

Create an SSH tunnel to access the OpenClarity server UI and API locally. Replace placeholders with your actual key path and the OpenClarity SSH address.

```bash
ssh -N -L 8080:localhost:80 -i  "<Path to the SSH key specified during install>" ubuntu@<OpenClarity SSH Address copied during install>

```

--------------------------------

### Open SSH tunnel to OpenClarity

Source: https://openclarity.io/docs/getting-started/deploy-azure

Establishes a local port forwarding tunnel to access the OpenClarity UI and API securely.

```bash
ssh -N -L 8080:localhost:80 -i  "<Path to the SSH key specified during install>" ubuntu@<OpenClarity SSH Address copied during install>
```

--------------------------------

### Report Scan Results to OpenClarity Backend

Source: https://openclarity.io/docs/usage/command_line

To report results to the OpenClarity backend, you must first create an asset and an asset scan object. This requires obtaining an asset-scan-id.

```bash
ASSET_ID=$(./bin/openclarity-cli asset-create --file assets/dir-asset.json --server http://localhost:8080/api) --jsonpath {.id}
ASSET_SCAN_ID=$(./bin/openclarity-cli asset-scan-create --asset-id $ASSET_ID --server http://localhost:8080/api) --jsonpath {.id}
./bin/openclarity-cli scan --config ~/testConf.yaml --server http://localhost:8080/api --asset-scan-id $ASSET_SCAN_ID
```

--------------------------------

### Port forward to OpenClarity gateway

Source: https://openclarity.io/docs/getting-started/deploy-kubernetes

Maps local port 8080 to the OpenClarity gateway service for UI access.

```bash
kubectl port-forward -n openclarity service/openclarity-gateway 8080:80
```

--------------------------------

### Convert SSH public key

Source: https://openclarity.io/docs/getting-started/deploy-azure

Converts an existing RSA public key to the SSH2 format required for the Azure deployment.

```bash
ssh-keygen -e -f ~/.ssh/id_rsa.pub > ~/.ssh/id_rsa2.pub
```

--------------------------------

### Stop OpenClarity Services with Docker Compose

Source: https://openclarity.io/docs/getting-started/deploy-docker

This command stops and removes the containers, networks, and volumes created by the Docker Compose file. Use --remove-orphans to clean up any containers not managed by the current Compose file.

```bash
docker compose --project-name openclarity --file docker-compose.yml down --remove-orphans
```

--------------------------------

### API Schemas Overview

Source: https://openclarity.io/docs/api

A reference list of all available data schemas within the OpenClarity API, categorized by functional domain.

```APIDOC
## API Schemas

### Overview
The OpenClarity API utilizes a wide range of schemas to manage security scanning, asset inventory, and vulnerability reporting.

### Schema Categories
- **Scan Management**: Scan, ScanTemplate, ScanStatus, ScanSummary, ScanConfigs, ScanConfig
- **Asset Management**: Assets, AssetCommon, Asset, VMInfo, PodInfo, ContainerInfo, ContainerImageInfo, DirInfo
- **Findings & Vulnerabilities**: Findings, Vulnerability, VulnerabilitySeverity, VulnerabilityFix, Malware, Rootkit, Secret, Exploit, Misconfiguration
- **Provider & Infrastructure**: CloudProvider, SecurityGroup, Tag, RootVolume, Provider
- **Reporting & Stats**: ScanFindingsSummary, VulnerabilitySeveritySummary, AssetScanStats, ScanEstimation, CostBreakdownComponent
- **Configuration**: InfoFinderConfig, VulnerabilitiesConfig, SBOMConfig, MalwareConfig, RootkitsConfig, SecretsConfig, MisconfigurationsConfig, ExploitsConfig, PluginsConfig

### Common Response Schemas
- **ApiResponse**: Standard wrapper for API responses.
- **SuccessResponse**: Standard success indicator.
- **Metadata**: Standard metadata fields for resources.
- **MetadataReadOnly**: Read-only metadata fields.
```

--------------------------------

### Uninstall OpenClarity

Source: https://openclarity.io/docs/getting-started/deploy-gcp

Removes the OpenClarity deployment using the gcloud deployment-manager.

```bash
gcloud deployment-manager deployments delete <openclarity deployment name>
```

--------------------------------

### Uninstall OpenClarity

Source: https://openclarity.io/docs/getting-started/deploy-kubernetes

Removes the OpenClarity release from the Kubernetes cluster.

```bash
helm uninstall openclarity --namespace openclarity
```

--------------------------------

### Stop OpenClarity Stack

Source: https://openclarity.io/docs/contributing

Shut down the local OpenClarity stack and remove associated volumes.

```bash
docker compose --project-name openclarity \
               --file installation/docker/docker-compose.yml \
               down --remove-orphans --volumes
```

--------------------------------

### Retrieve ScanEstimation results

Source: https://openclarity.io/docs/features/cost-estimation

Query the scanEstimations endpoint to retrieve the status and cost summary once the state reaches Done.

```json
{
   "assetIDs":[
      "d337bd07-b67f-4cf0-ac43-f147fce7d1b2"
   ],
   "assetScanEstimations":[
      {
         "id":"23082244-0fb6-4aca-8a9b-02417dfc95f8"
      }
   ],
   "deleteAfter":"2023-10-08T17:33:52.512829081Z",
   "endTime":"2023-10-08T15:33:52.512829081Z",
   "id":"962e3a10-05fb-4c5d-a773-1198231f3103",
   "revision":5,
   "scanTemplate":{
      "assetScanTemplate":{
         "scanFamiliesConfig":{
            "sbom":{
               "enabled":true
            }
         }
      },
      "scope":"contains(assetInfo.tags, '{\"key\":\"scanestimation\",\"value\":\"test\"}')"
   },
   "startTime":"2023-10-08T15:33:37.513073573Z",
   "state":{
      "state":"Done",
      "stateMessage":"1 succeeded, 0 failed out of 1 total asset scan estimations",
      "stateReason":"Success"
   },
   "summary":{
      "jobsCompleted":1,
      "jobsLeftToRun":0,
      "totalScanCost":0.0006148403,
      "totalScanSize":3,
      "totalScanTime":12
   },
   "ttlSecondsAfterFinished":7200
}
```

--------------------------------

### Delete Kubernetes cluster

Source: https://openclarity.io/docs/getting-started/deploy-kubernetes

Removes the local Kind cluster after cleanup.

```bash
kind delete clusters openclarity-k8s
```
Tokens:
Raw