Using Compliance Scanner for PCF

Page last updated:

This topic describes how to use Compliance Scanner for Pivotal Cloud Foundry.

Compliance Scanner for PCF performs one errand that starts scanning. When this errand is triggered, it starts the scanning errand on each VM, including the oscap_store VM that the tile creates.

The scanning errand is set to Off by default. This is because Compliance Scanner for PCF only scans tiles that are already present when you deploy it. If you install other tiles during the same time Compliance Scanner for PCF is installed, the additional tiles are not scanned.

The scan errand on each VM does generate the Security Content Automation Protocol (SCAP) tests each time by running XGen on XFiles.

Ways to Scan VMs

You can scan VMs using the tile UI or the command line:

Scan Using the Compliance Scanner for PCF Tile

Scanning VMs involves three procedures:

  1. Scan the VMs
  2. Retrieve Log Files
  3. Find Scan Output

Scan the VMs

To begin scanning, do the following:

  1. Confirm that your scan is configured correctly with the benchmarks and log formats you want output.

    For more information on configuring your scan, see Configure Scans.

  2. Navigate to the Ops Manager Installation Dashboard.

  3. Click REVIEW PENDING CHANGES.

  4. Enable the checkboxes for the Compliance Scanner for PCF tile and the Run config scans on PAS errand.

    Review pending changes page with Compliance Scanner for PCF selected and Run config scans on P
AS errand selected

    A scan is triggered at the end.

    Note: If there are configuration changes from add-ons or tiles other than Compliance Scanner for PCF, leave those products’ and errands’ checkboxes enabled if you want those changes to be applied. If there are no changes from other sources, only the Compliance Scanner for PCF tile needs to have its checkbox enabled.

  5. Click APPLY CHANGES.

    When scanning is finished, a second errand is triggered by the Run-config-scans-on-PAS errand to retrieve the logs from each VM. On each VM, there is only one log file per format and one ZIP log file at a time. If you run any subsequent scans these files are overwritten.

Retrieve Log Files

To review the logs for a completed scan using the Compliance Scanner for PCF tile, do the following:

  1. When the changes have been applied, return to the Installation Dashboard and click the Compliance Scanner for PCF tile.

    dialog at the end of apply changes

  2. Click the Status tab and download the oscap_store log file.

    This downloads the log file containing scan results from the oscap_store VM to Ops Manager. If you select the download icon multiple times, a list of ZIP files is created in Ops Manager, each with a different timestamp.

  3. Click the Logs tab and click on the filename of the ZIP log file.

    This downloads the scan results from the Ops Manager to your local machine.

    The logs pane from where the zipped scan logs can be downloaded

    The timestamp indicates when the scan was initiated.

  4. Decompress the downloaded file.

    The contents of the downloaded file depend on the formats and benchmarks you selected during configuration. For example, a report in HTML format from the Base Xenial benchmark, might look like this.

    HTML report header

    See a larger version of this image.

Find Scan Output

The oscap_store ZIP file contains scan results from the oscap_store VM.
The results of the scan are at the following path:

  oscap_store/scanner/scan_results/output

The naming syntax for each log file is the following:

  BENCHMARK_COMPONENT_UUID.FORMAT

Where:

  • BENCHMARK is the benchmark that was used for the scan.
  • COMPONENT is the VM that was scanned.
  • UUID is the UUID for the VM that was scanned.
  • FORMAT is the format of the file.

For example, the oscap_store folder directory looks similar to the following image:

oscap_store file structure

The number of log files in the output directory can be calculated as follows:

  (v + i) * f * b

Where:

  • v is the number of VMs in your PCF deployment.
  • i is the number of additional instances for any VM in your PCF deployment.
  • f is the number of formats you configured in Configure Scans.
  • b is the number of benchmarks you configured in Configure Scans.

Scan Using the Command Line

You also have the option of scanning VMs using the command line. There are two ways to do this:

Scan and Retrieve Log Files

To start a new scan and retrieve the logs for the completed scan using the command line, do the following:

  1. Log in to the BOSH Director.
    1. On the Ops Manager VM, create an alias in the BOSH CLI for your BOSH Director IP address. For example:
      $ bosh alias-env my-env -e 10.0.0.3
    2. Log in to the BOSH Director, specifying the newly created alias. For example:
      $ bosh -e my-env log-in
  2. Run bosh deployments to list all the deployment names. For example:

    Name                      Release(s)                    Stemcell(s)
    pivotal-container-service backup-and-restore-sdk/1.8.0  bosh-google-kvm-ubuntu-xenial-go_agent/97.47   -
                              bosh-dns/1.10.0
                              bosh-dns-aliases/0.0.3
                              bpm/0.6.0
                              cf-mysql/36.14.0
                              docker/32.0.3
                              kubo/0.21.13
                              kubo-service-adapter/1.2.5
                              oscap/0.1.61
                              pks-telemetry/0.9.4
    scanner-f9822a33c2e0d04cb bosh-dns/1.10.0               bosh-google-kvm-ubuntu-xenial-go_agent/170.19  -
                              bosh-dns-aliases/0.0.3
                              clamav/1.4.41
                              ipsec/1.9.14
                              ipsec-verifier/1.9.14
                              oscap/0.1.61
    service-instance          bosh-dns/1.10.0               bosh-google-kvm-ubuntu-xenial-go_agent/97.47
                              bosh-dns-aliases/0.0.3        pivotal-container-service
                              bpm/0.6.0
                              cfcr-etcd/1.4.1
                              kubo/0.21.13
    

  3. Find the scanner deployment in the list. It appears as scanner-DEPLOYMENT-UUID, where DEPLOYMENT-UUID is the UUID of your deployment.

  4. Run the following command to start the scan and download the logs:

  bosh -e my-env -d scanner-DEPLOYMENT-UUID run-errand scan_results --download-logs --logs-dir PATH-TO-SAVE-SCAN-RESULTS

Where:

  • scanner-DEPLOYMENT-UUID is the name of your scanner deployment.
  • PATH-TO-SAVE-SCAN-RESULTS is the directory in which you would like to save your logs to. You may omit --logs-dir PATH-TO-SAVE-SCAN-RESULTS if you want the logs to be saved to your current directory.

For example:

bosh -e my-env -d scanner-f9822a33c2e0d04cb run-errand scan_results --download-logs --logs-dir scanner/logs/20190131

Note: The files generated use the most recent configuration of your tile. To see what the current settings are, see Configure Scans.

Retrieve Existing Log Files

To retrieve existing logs for the most recent completed scan using the command line, use the following command:

  bosh -e my-env -d scanner-DEPLOYMENT-UUID logs --only=scan_results --dir PATH-TO-SAVE-SCAN-RESULTS

Where:

  • scanner-DEPLOYMENT-UUID is the name of your scanner deployment.
  • PATH-TO-SAVE-SCAN-RESULTS is the directory in which you would like to save your logs to. You may omit --dir PATH-TO-SAVE-SCAN-RESULTS if you want the logs to be saved to your current directory.

For example:

bosh -e my-env -d scanner-f9822a33c2e0d04cb logs --only=scan_results --dir scanner/logs/20190131

Access Log Files

To access your saved logs, unzip the output ZIP file.

The naming syntax for each log file is the following:

  BENCHMARK_COMPONENT_UUID.FORMAT

Where:

  • BENCHMARK is the benchmark that was used for the scan.
  • COMPONENT is the VM that was scanned.
  • UUID is the UUID for the VM that was scanned.
  • FORMAT is the format of the file.

For example, the output folder directory looks similar to the following image:

output folder structure

View Tests on VMs

For every configuration rule that is checked, there is a corresponding test written in YAML test files residing on each VM. You can use these files as reference for internal test development or to validate that the test matches the description.

To view tests on VMS, do the following:

  1. Use the BOSH CLI to SSH into a component VM. For more information, see BOSH SSH.
  2. Navigate to the following path:

    /var/vcap/packages/oscap/xfiles
    
  3. Search for the test ID and open the corresponding file.