Advanced documentation

Compliance Air gap with the API with PowerShell

Use of the scripts requires authentication by following this process.

Compliance Air gap can only be used with assets already registered in Cyberwatch.

In case the TLS certificate of the Cyberwatch server cannot be recognized by the machine running this script, it is necessary to execute the following code snippet before the scripts:

add-type @"
    using System.Net;
    using System.Security.Cryptography.X509Certificates;
    public class TrustAllCertsPolicy : ICertificatePolicy {
        public bool CheckValidationResult(
            ServicePoint srvPoint, X509Certificate certificate,
            WebRequest request, int certificateProblem) {
            return true;
        }
    }
"@
[System.Net.ServicePointManager]::CertificatePolicy = New-Object TrustAllCertsPolicy

Compliance Air gap Scripts + Usage

  1. Retrieve the Compliance Air gap download script and the Compliance Air gap upload script, fill in the $API_URL and $CREDENTIALS variables.

  2. After executing the download script, a compliance_scripts folder is created that contains the script to generate results.

  3. To execute the script, you must move the entire folder to the asset you want to scan and run the run script as explained below. To avoid any risk of executing an undesirable script, take the folder itself, not just its content.

    • For Linux: bash ./compliance.sh > result.txt
    • For Windows using PowerShell: .\compliance.ps1 | Out-File -Encoding ASCII -FilePath result.txt

    This will create a result.txt file containing the results.

    Then move the result.txt file to the uploads folder on the system with the upload script.

  4. Send the script results present in the uploads folder with the Compliance Air gap upload script.

Download script for Compliance Air gap

Display the script source code
# -------------------------------------
# CONFIGURATION
# Please check and complete these items
# -------------------------------------

$API_URL = ""
$CREDENTIALS = "access_key:secret_key"

# -------------------------
# RUN
# -------------------------

$encodedCreds = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($CREDENTIALS))

$os = Read-Host -Prompt "Input one OS (format from $API_URL/cbw_assets/os) to get the scripts, ex: 'windows_10_21h1_64/ubuntu_2004_64'"
$repository_input = Read-Host -Prompt "Input one or multiple repositories to fetch, ex: 'CIS_Benchmark, Security_Best_Practices, ...'"

$repository_array = $repository_input -split ", "

Function FetchImporterScripts {
<#
.SYNOPSIS
        Example script to fetch Compliance Air gap scripts
#>

  Write-Output "-------------------------------------------"
  Write-Output "Cyberwatch - Fetch Compliance Air gap scripts"
  Write-Output "-------------------------------------------"

  # Test the client connection
  Write-Output "INFO: Checking API connection and credentials..."
  try {
    $response = Invoke-WebRequest -URI $API_URL/api/v3/ping -Method Get -Headers @{
      "Accept"      = "application/json; charset=utf-8"
      Authorization = "Basic $encodedCreds"
    }

    $response.Content
  }
  catch {
    Write-Output "ERROR: Connection failed. Please check the following error message : '$_'"
    Return
  }

  # Clean old files
  Write-Output "INFO: Cleaning old files..."
  Remove-Item -LiteralPath ".\compliance_scripts" -Force -Recurse -ErrorAction Ignore
  Write-Output "INFO: Done."

  # Create the base folders
  New-Item -path ".\compliance_scripts" -Force -ItemType Directory | Out-Null
  New-Item -path ".\uploads" -Force -ItemType Directory | Out-Null

  # Fetch available scanning scripts from the API for the OS
  Write-Output "INFO: Fetching filtered compliance scripts for OS: $os..."

  $uri = "$API_URL/api/v2/compliances/scripts?os=$os&"
  $repository_array | ForEach-Object {
      $uri += "repositories%5B%5D=$_&"
  }
    
  Write-Output $uri
    
  $response = Invoke-RestMethod -URI $uri -Method Get -Headers @{
      "Accept"      = "application/json; charset=utf-8"
      Authorization = "Basic $encodedCreds"
  }

    # Fetch content of each script and attachments
  $response | ForEach-Object {
    Write-Output "INFO: Fetching content for '$($_.code)' ..."
    $scanning_script = ($_)
    $scanning_script_path = ".\compliance_scripts\"+$scanning_script.filename.ToLower().replace("::", "\")
    Write-Output $scanning_script.filename
    $scanning_script.script_content | New-Item -path $scanning_script_path -Force -ItemType File | Out-Null 
    Write-Output "INFO: Script saved at $($(Resolve-Path -Path $scanning_script_path).Path)."
  }

  Write-Output "---------------------------------------------------------------------"
  Write-Output "Script completed!"
  Write-Output "To continue, please now:"
  Write-Output "1) Run the fetched scripts with 'compliance.ps1' or 'compliance.sh' on the targeted systems"
  Write-Output "2) Put the results of the scripts as TXT files in the 'upload' folder"
  Write-Output "3) Run the compliance 'upload' script"
  Write-Output "---------------------------------------------------------------------"

}

FetchImporterScripts

Upload script for Compliance Air gap

Display the script source code
# -------------------------------------
# CONFIGURATION
# Please check and complete these items
# -------------------------------------

$API_URL = ""
$CREDENTIALS = "access_key:secret_key"

# -------------------------
# RUN
# -------------------------

Write-Output "-------------------------------------------"
Write-Output "Cyberwatch - Send Compliance Air gap results for analysis"
Write-Output "-------------------------------------------"

$encodedCreds = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($CREDENTIALS))

Function SendResultsImporter {
    <#
.SYNOPSIS
        Example script to send Compliance Air gap scripts results
#>

    try {
        $response = Invoke-WebRequest -URI $API_URL/api/v3/ping -Method Get -Headers @{
            "Accept"      = "application/json; charset=utf-8"
            Authorization = "Basic $encodedCreds"
        }

        $response.Content
    }
    catch {
        Write-Output "ERROR: Connection failed. Please check the following error message : '$_'"
        Return
    }

    # Load results and send them to Cyberwatch
    Write-Output "INFO: Searching for available results..."
    $available_results = Get-ChildItem -Recurse -File -Path ".\uploads"
    Write-Output "INFO: Done. Found $($available_results.count) results to be processed and sent for analysis."

    $available_results | ForEach-Object {
        Write-Output "INFO: Reading $($_.FullName) content..."
        $content = [IO.File]::ReadAllText($_.FullName)
        Write-Output "INFO: Sending $($_.FullName) content to the API..."
        $body_content = @{ output = $content } | ConvertTo-Json
        $response = Invoke-WebRequest -URI $API_URL/api/v2/compliances/scripts -Method POST -Body $body_content -Headers @{
            "Accept"      = "application/json; charset=utf-8"
            "Content-Type" = "application/json"
            Authorization = "Basic $encodedCreds"
        }
        Write-Output "INFO: Done."
    }

    Write-Output "---------------------------------------------------------------------"
    Write-Output "Script completed!"
    Write-Output "Your scans are now being processed by your Cyberwatch nodes."
    Write-Output "Please log on $API_URL to see the results."
    Write-Output "---------------------------------------------------------------------"

}

SendResultsImporter

Back to top