Create Script-based Checks

Updated Aug 30, 2023

Create script-based checks

In addition to the built-in library of standards-based checks, Slang supports checks written in other common scripting languages. Scripts can be in any format or language that will run on the scan target.

For Windows, use:

For Linux, use:

If you know your scan targets support anything else, like Python or Ruby, you can use those languages as well.

Before you begin

Steps

  1. Create a script-based check.
  2. Add a script-based check to a rule.
  3. Test the script-based check.

Step 1: Create a script-based check

Script checks use the Script Check Engine (SCE) standard. For more information, see Script Check Engine. You can use Slang parameters with script-based checks the same way as regular Slang checks. Save script-based checks in the ~/Slang/check_scripts folder.

  1. In Visual Studio Code (VS Code), create a file called <check_name>.ps1 in the /Slang/check_scriptsfolder.

  2. Add script content.

    For example:

      # This script checks the TPM status using TPM. #
      # clear all errors
      $error.Clear()
      # check tpm is present and ready
      try {
        $TPM = Get-TPM
        Write-Output $TPM
        if ($TPM -and $TPM.TpmPresent -and $TPM.TpmReady) {
          Write-Output "Result: PASS"
          exit $env:XCCDF_RESULT_PASS
        } else {
          Write-Output "Result: FAIL"
          exit $env:XCCDF_RESULT_FAIL
        }
      } catch {
          Write-Output $_
          Write-Output "Result: ERROR"
          exit $env:XCCDF_RESULT_ERROR
      }     
  3. Save the file.

Step 2: Add a script-based check to a rule

Once you have added scripts to your ~/Slang/check_scripts folder, you can use them in Slang rules. For more information about adding rules, see Add rules to the project.

  1. In VS Code, select File > Open Folder and navigate to your project.

  2. Create a file called <rule_id>.slang.

  3. Add this content:

    Rule:
      title: <rule_name>
      checks:
        - common.script:
        script_file: <check_name>.ps1
  4. (Optional) Export parameters as environment variables to use in your script.

For example:

- common.script:
  script_file: <check_name>.ps1
  set_environment_variables:
      <environment_variable>: ${<parameter_name>}

In SCE, exported variables are prefixed by XCCDF_VALUE_. Use the environment variables in your script as you would any other environment variable in that scripting language. For example, $env:XCCDF_VALUE_<environment_variable> in PowerShell and $XCCDF_VALUE_<environment_variable> in bash.

  1. Save the rule file.
  2. Run this command to export your project including the new script-based check:
    slang export <project_name> <project_name>.xml

Step 3: Test the script-based check

  1. Run a scan.

    If you have access to a Windows 10 device to scan against and have completed the steps in Test a Slang project, run this command to export and test your project using a profile:

    slang export <project_name> <project_name>.xml --scan_config <config_name> --profile profile.<profile_name>.slang --elevate y
  2. Review the results to make sure the script worked as expected.

    For example, check for XCCDF_RESULT_PASS, XCCDF_RESULT_FAIL, XCCDF_RESULT_ERROR, or XCCDF_RESULT_UNKNOWN.

Next steps

See also