---
agentTools:
  projectIndex: https://regscale.readme.io/llms.txt
---

# OpenSCAP

The RegScale CLI OpenSCAP integration imports compliance scan results from OpenSCAP into RegScale as vulnerabilities and control assessments. It supports ARF (Asset Reporting Format), XCCDF, and CSV export formats, and can pull files from local disk or directly from an S3 bucket.

## Prerequisites

<br />

* RegScale CLI installed and configured (`regscale init` completed)
  * OpenSCAP scan output in one of the supported formats: ARF (`.xml`), XCCDF (`.xml`), or CSV (`.csv`)
    * A Security Plan (or other parent record) already created in RegScale
      * *(Optional)* AWS credentials configured if reading scan files from S3

***

<br />

## Configuration

Add the following keys to your `init.yaml` (all optional):

| Key                           | Default        | Description                                                                                  |
| ----------------------------- | -------------- | -------------------------------------------------------------------------------------------- |
| `openscapComplianceFramework` | `NIST800-53R5` | Compliance framework used by `sync_compliance` when not auto-detected from the Security Plan |
| `openscapCceNistOverridePath` | *(none)*       | Path to a custom YAML file that overrides the built-in CCE-to-NIST control mapping           |

All keys can also be supplied as environment variables using the same name (e.g. `OPENSCAP_COMPLIANCE_FRAMEWORK`).

***

## Commands

### `import_arf`

Import OpenSCAP **ARF** (Asset Reporting Format) scan results. Accepts a single `.xml` file, a directory of `.xml` files, or an S3 source.

```bash
regscale openscap import_arf \
  --path /path/to/results.xml \
  --regscale_id 42 \
  --regscale_module securityplans
```

**Options**

| Option                    | Required                         | Description                                                            |
| ------------------------- | -------------------------------- | ---------------------------------------------------------------------- |
| `--path`                  | One of `--path` or `--s3_bucket` | Local file or directory of `.xml` files                                |
| `--regscale_id`           | Yes                              | ID of the target RegScale record                                       |
| `--regscale_module`       | Yes (default: `securityplans`)   | RegScale parent module                                                 |
| `--s3_bucket`             | One of `--path` or `--s3_bucket` | S3 bucket to download scan files from                                  |
| `--s3_prefix`             | No                               | Folder prefix within the S3 bucket                                     |
| `--aws_profile`           | No                               | AWS named profile (env: `AWS_PROFILE`)                                 |
| `--aws_access_key_id`     | No                               | AWS access key ID (env: `AWS_ACCESS_KEY_ID`)                           |
| `--aws_secret_access_key` | No                               | AWS secret access key (env: `AWS_SECRET_ACCESS_KEY`)                   |
| `--aws_session_token`     | No                               | AWS session token for temporary credentials (env: `AWS_SESSION_TOKEN`) |

***

### `import_xccdf`

Import standalone OpenSCAP **XCCDF** results. Accepts a single `.xml` file, a directory of `.xml` files, or an S3 source.

```bash
regscale openscap import_xccdf \
  --path /path/to/xccdf-results.xml \
  --regscale_id 42 \
  --regscale_module securityplans
```

**Options** — same as [`import_arf`](#import_arf) above.

***

### `import_csv`

Import OpenSCAP **CSV** export results. Accepts a single `.csv` file, a directory of `.csv` files, or an S3 source.

```bash
regscale openscap import_csv \
  --path /path/to/results.csv \
  --regscale_id 42 \
  --regscale_module securityplans
```

**Options** — same as [`import_arf`](#import_arf) above, but `--path` points to `.csv` files.

***

### `sync_compliance`

Parse an ARF or XCCDF scan file and create or update **control assessments** in RegScale based on the pass/fail results. The compliance framework is auto-detected from the Security Plan or can be overridden.

```bash
regscale openscap sync_compliance \
  --path /path/to/results.xml \
  --regscale_id 42
```

Override the compliance framework explicitly:

```bash
regscale openscap sync_compliance \
  --path /path/to/results.xml \
  --regscale_id 42 \
  --framework NIST800-53R4
```

**Options**

| Option          | Required | Description                                                                       |
| --------------- | -------- | --------------------------------------------------------------------------------- |
| `--path`        | Yes      | Path to the ARF or XCCDF scan file                                                |
| `--regscale_id` | Yes      | Security Plan ID in RegScale                                                      |
| `--framework`   | No       | Override framework (e.g. `NIST800-53R5`). Auto-detected from the SSP when omitted |

***

## S3 Integration

All import commands support pulling scan files directly from an Amazon S3 bucket, eliminating the need to copy files to the local machine first.

AWS credential resolution order (highest to lowest priority):

1. `--aws_access_key_id` / `--aws_secret_access_key` flags (or matching env vars)
2. `--aws_profile` (or `AWS_PROFILE` env var)
3. `init.yaml` AWS configuration
4. Default AWS credential chain (instance profile, `~/.aws/credentials`, etc.)

**Example — import all ARF files from an S3 prefix:**

```bash
regscale openscap import_arf \
  --s3_bucket my-scan-results \
  --s3_prefix openscap/2024-Q4/ \
  --regscale_id 42 \
  --regscale_module securityplans
```

> `--path` and `--s3_bucket` are mutually exclusive. Exactly one must be provided.

***

## Supported File Formats

| Format                       | Command        | Extension | Notes                                          |
| ---------------------------- | -------------- | --------- | ---------------------------------------------- |
| ARF (Asset Reporting Format) | `import_arf`   | `.xml`    | Preferred; includes full asset context         |
| XCCDF Results                | `import_xccdf` | `.xml`    | Standalone XCCDF result streams                |
| CSV Export                   | `import_csv`   | `.csv`    | Use OpenSCAP's `--export-variables` CSV output |

***

## Custom CCE-to-NIST Mapping

By default, the integration uses a built-in CCE-to-NIST control mapping. To override this (for example, to support a custom STIG or organizational mapping), set `openscapCceNistOverridePath` in `init.yaml` to a YAML file with the following structure:

```yaml
CCE-12345-6: AC-2
CCE-67890-1: SI-3
```

***

## Typical Workflow

1. Run OpenSCAP against your target systems and export results.
2. Import findings into your RegScale Security Plan:
   ```bash
   regscale openscap import_arf --path ./results/ --regscale_id <ssp_id> --regscale_module securityplans
   ```
3. Sync compliance control assessments:
   ```bash
   regscale openscap sync_compliance --path ./results/result.xml --regscale_id <ssp_id>
   ```
4. Review findings and assessments in the RegScale UI.