From 7a33a918b0a283f7b270da1a136974808c073595 Mon Sep 17 00:00:00 2001 From: Vasundhara Jagdale Date: Mon, 27 Feb 2023 12:32:40 +0530 Subject: [PATCH] Foreport-6384 (#6466) * DOCS: Generate cli.md with rake docs:cli Signed-off-by: Sonu Saha * Remove unused require Signed-off-by: Sonu Saha * FORMAT: Use html dl, dt, dd tags for displaying subcommands Signed-off-by: Sonu Saha * REFACTOR: Remove repetitive dl closing for subcommands of single command Signed-off-by: Sonu Saha --------- Signed-off-by: Sonu Saha Co-authored-by: Sonu Saha --- docs-chef-io/content/inspec/cli.md | 1071 +++++++++++++++++----------- tasks/docs.rb | 15 +- 2 files changed, 644 insertions(+), 442 deletions(-) diff --git a/docs-chef-io/content/inspec/cli.md b/docs-chef-io/content/inspec/cli.md index cf004c9c6..bd5283959 100644 --- a/docs-chef-io/content/inspec/cli.md +++ b/docs-chef-io/content/inspec/cli.md @@ -31,38 +31,39 @@ inspec archive PATH This subcommand has the following additional options: -* `--airgap`, `--no-airgap` - Fallback to using local archives if fetching fails. -* `--ignore-errors`, `--no-ignore-errors` - Ignore profile warnings. -* `-o`, `--output=OUTPUT` - Save the archive to a path. -* `--overwrite`, `--no-overwrite` - Overwrite existing archive. -* `--profiles-path=PROFILES_PATH` - Folder which contains referenced profiles. -* `--tar`, `--no-tar` - Generates a tar.gz archive. -* `--vendor-cache=VENDOR_CACHE` - Use the given path for caching dependencies, (default: `~/.inspec/cache`). -* `--zip`, `--no-zip` - Generates a zip archive. +
+
--airgap, --no-airgap
+
Fallback to using local archives if fetching fails.
-## automate +
--auto-install-gems, --no-auto-install-gems
+
Auto installs gem dependencies of the profile or resource pack.
-Communicates with Chef Automate. +
--ignore-errors, --no-ignore-errors
+
Ignore profile warnings.
-### Syntax +
-o, --output=OUTPUT
+
Save the archive to a path.
-This subcommand has the following syntax: +
--overwrite, --no-overwrite
+
Overwrite existing archive.
-```bash -inspec automate SUBCOMMAND -``` +
--profiles-path=PROFILES_PATH
+
Folder which contains referenced profiles.
+ +
--tar, --no-tar
+
Generates a tar.gz archive.
+ +
--vendor-cache=VENDOR_CACHE
+
Use the given path for caching dependencies, (default: ~/.inspec/cache).
+ +
--zip, --no-zip
+
Generates a zip archive.
+ +
## check -Verify the metadata in the `inspec.yml` file, verify that control blocks have the correct fields (title, description, impact), and define that all controls have visible tests and the controls are not using deprecated InSpec DSL code. +Verify the metadata in the `inspec.yml` file, verify that control blocks have the correct fields (title, description, impact), and define that all controls have visible tests and the controls are not using deprecated inspec dsl code ### Syntax @@ -76,18 +77,49 @@ inspec check PATH This subcommand has the following additional options: -* `--format=FORMAT` - The output format to use. Valid values: `json` and `doc`. Default value: `doc`. -* `--profiles-path=PROFILES_PATH` - Folder which contains referenced profiles. -* `--vendor-cache=VENDOR_CACHE` - Use the given path for caching dependencies, (default: `~/.inspec/cache`). -* `--with-cookstyle`, `--no-with-cookstyle` - Enable or disable cookstyle checks. +
+
--auto-install-gems, --no-auto-install-gems
+
Auto installs gem dependencies of the profile or resource pack.
+ +
--format=FORMAT
+
The output format to use. Valid values: `json` and `doc`. Default value: `doc`.
+ +
--profiles-path=PROFILES_PATH
+
Folder which contains referenced profiles.
+ +
--vendor-cache=VENDOR_CACHE
+
Use the given path for caching dependencies, (default: ~/.inspec/cache).
+ +
--with-cookstyle, --no-with-cookstyle
+
Enable or disable cookstyle checks.
+ +
+ +## clear_cache + +Clears the inspec cache. useful for debugging. + +### Syntax + +This subcommand has the following syntax: + +```bash +inspec clear_cache +``` + +### Options + +This subcommand has the following additional options: + +
+
--vendor-cache=VENDOR_CACHE
+
Use the given path for caching dependencies, (default: `~/.inspec/cache`).
+ +
## detect -Detects the target OS. +Detects the target os. ### Syntax @@ -101,80 +133,120 @@ inspec detect This subcommand has the following additional options: -* `-b`, `--backend=BACKEND` - Choose a backend: local, ssh, winrm, docker. -* `--bastion-host=BASTION_HOST` - Specifies the bastion host if applicable. -* `--bastion-port=BASTION_PORT` - Specifies the bastion port if applicable. -* `--bastion-user=BASTION_USER` - Specifies the bastion user if applicable. -* `--ca-trust-file=PATH_TO_CA_TRUST_FILE` - Specify CA certificate required for SSL authentication (WinRM). -* `--client-cert=PATH_TO_CLIENT_CERTIFICATE` - Specify client certificate required for SSL authentication (WinRM). -* `--client-key=PATH_TO_CLIENT_KEY` - Specify client key required with client certificate for SSL authentication (WinRM). -* `--client-key-pass=CLIENT_CERT_PASSWORD` - Specify client certificate password, if required for SSL authentication (WinRM). -* `--config=CONFIG` - Read configuration from the JSON file (`-` reads from stdin). -* `--docker-url` - Provides a path to the Docker API endpoint (Docker). -* `--enable-password=ENABLE_PASSWORD` - Password for enable mode on Cisco IOS devices. -* `--format=FORMAT` +
+
-b, --backend=BACKEND
+
Choose a backend: local, ssh, winrm, docker.
-* `--host=HOST` - Specify a remote host which is tested. -* `--insecure`, `--no-insecure` - Disable SSL verification on select targets. -* `-i`, `--key-files=one two three` - Login key or certificate file for a remote scan. -* `--password=PASSWORD` - Login password for a remote scan, if required. -* `--path=PATH` - Login path to use when connecting to the target (WinRM). -* `-p`, `--port=N` - Specify the login port for a remote scan. -* `--podman-url` - Provides the path to the Podman API endpoint. Defaults to unix:///run/user/$UID/podman/podman.sock for rootless container, unix:///run/podman/podman.sock for rootful container (for this you need to execute inspec as root user). -* `--proxy-command=PROXY_COMMAND` - Specifies the command to use to connect to the server. -* `--self-signed`, `--no-self-signed` - Allow remote scans with self-signed certificates (WinRM). -* `--shell`, `--no-shell` - Run scans in a subshell. Only activates on Unix. -* `--shell-command=SHELL_COMMAND` - Specify a particular shell to use. -* `--shell-options=SHELL_OPTIONS` - Additional shell options. -* `--ssl`, `--no-ssl` - Use SSL for transport layer encryption (WinRM). -* `--ssl-peer-fingerprint` - Specify SSL peer fingerprint in place of certificates for SSL authentication (WinRM). -* `--sudo`, `--no-sudo` - Run scans with sudo. Only activates on Unix and non-root user. -* `--sudo-command=SUDO_COMMAND` - Alternate command for sudo. -* `--sudo-options=SUDO_OPTIONS` - Additional sudo options for a remote scan. -* `--sudo-password=SUDO_PASSWORD` - Specify a sudo password, if it is required. -* `-t`, `--target=TARGET` - Simple targeting option using URIs, e.g. ssh://user:pass@host:port. -* `--target-id=TARGET_ID` - Provide a ID which will be included on reports. -* `--user=USER` - The login user for a remote scan. -* `--winrm-basic-auth-only`, `--no-winrm-basic-auth-only` - Whether to use basic authentication, defaults to false (WinRM). -* `--winrm-disable-sspi`, `--no-winrm-disable-sspi` - Whether to use disable sspi authentication, defaults to false (WinRM). -* `--winrm-transport=WINRM_TRANSPORT` - Specify which transport to use, defaults to negotiate (WinRM). -* `--winrm-shell-type=WINRM_SHELL_TYPE` - Specify which shell type to use (powershell, elevated, or cmd), which defaults to powershell (WinRM). +
--bastion-host=BASTION_HOST
+
Specifies the bastion host if applicable.
+ +
--bastion-port=BASTION_PORT
+
Specifies the bastion port if applicable.
+ +
--bastion-user=BASTION_USER
+
Specifies the bastion user if applicable.
+ +
--ca-trust-file=CA_TRUST_FILE
+
Specify CA certificate required for SSL authentication (WinRM).
+ +
--client-cert=CLIENT_CERT
+
Specify client certificate for SSL authentication
+ +
--client-key=CLIENT_KEY
+
Specify client key required with client cert for SSL authentication
+ +
--client-key-pass=CLIENT_KEY_PASS
+
Specify client cert password, if required for SSL authentication
+ +
--config=CONFIG
+
Read configuration from JSON file (`-` reads from stdin).
+ +
--docker-url=DOCKER_URL
+
Provides path to Docker API endpoint (Docker). Defaults to unix:///var/run/docker.sock on Unix systems and tcp://localhost:2375 on Windows.
+ +
--enable-password=ENABLE_PASSWORD
+
Password for enable mode on Cisco IOS devices.
+ +
--format=FORMAT
+
--host=HOST
+
Specify a remote host which is tested.
+ +
--insecure, --no-insecure
+
Disable SSL verification on select targets.
+ +
-i, --key-files=one two three
+
Login key or certificate file for a remote scan.
+ +
--password=PASSWORD
+
Login password for a remote scan, if required.
+ +
--path=PATH
+
Login path to use when connecting to the target (WinRM).
+ +
--podman-url=PODMAN_URL
+
Provides the path to the Podman API endpoint. Defaults to unix:///run/user/$UID/podman/podman.sock for rootless container, unix:///run/podman/podman.sock for rootful container (for this you need to execute inspec as root user).
+ +
-p, --port=N
+
Specify the login port for a remote scan.
+ +
--proxy-command=PROXY_COMMAND
+
Specifies the command to use to connect to the server.
+ +
--self-signed, --no-self-signed
+
Allow remote scans with self-signed certificates (WinRM).
+ +
--shell, --no-shell
+
Run scans in a subshell. Only activates on Unix.
+ +
--shell-command=SHELL_COMMAND
+
Specify a particular shell to use.
+ +
--shell-options=SHELL_OPTIONS
+
Additional shell options.
+ +
--ssh-config-file=one two three
+
A list of paths to the ssh config file, e.g ~/.ssh/config or /etc/ssh/ssh_config.
+ +
--ssl, --no-ssl
+
Use SSL for transport layer encryption (WinRM).
+ +
--ssl-peer-fingerprint=SSL_PEER_FINGERPRINT
+
Specify SSL peer fingerprint in place of certificates for SSL authentication (WinRM).
+ +
--sudo, --no-sudo
+
Run scans with sudo. Only activates on Unix and non-root user.
+ +
--sudo-command=SUDO_COMMAND
+
Alternate command for sudo.
+ +
--sudo-options=SUDO_OPTIONS
+
Additional sudo options for a remote scan.
+ +
--sudo-password=SUDO_PASSWORD
+
Specify a sudo password, if it is required.
+ +
-t, --target=TARGET
+
Simple targeting option using URIs, e.g. ssh://user:pass@host:port
+ +
--target-id=TARGET_ID
+
Provide an ID which will be included on reports - deprecated
+ +
--user=USER
+
The login user for a remote scan.
+ +
--winrm-basic-auth-only, --no-winrm-basic-auth-only
+
Whether to use basic authentication, defaults to false (WinRM).
+ +
--winrm-disable-sspi, --no-winrm-disable-sspi
+
Whether to use disable sspi authentication, defaults to false (WinRM).
+ +
--winrm-shell-type=WINRM_SHELL_TYPE
+
Specify which shell type to use (powershell, elevated, or cmd), which defaults to powershell (WinRM).
+ +
--winrm-transport=WINRM_TRANSPORT
+
Specify which transport to use, defaults to negotiate (WinRM).
+ +
## env @@ -192,90 +264,78 @@ inspec env Run all test files at the specified locations. -The subcommand loads the given profiles, fetches their dependencies if needed, then connects to the target and executes any controls in the profiles. One or more reporters are used to generate the output. - -```ruby -exit codes: - 0 normal exit, all tests passed - 1 usage or general error - 2 error in plugin system - 3 fatal deprecation encountered - 100 normal exit, at least one test failed - 101 normal exit, at least one test skipped but none failed - 172 chef license not accepted +The subcommand loads the given profiles, fetches their dependencies if needed, then connects to the target and executes any controls in the profiles. +One or more reporters are used to generate the output. +``` +Exit codes: + 0 Normal exit, all tests passed + 1 Usage or general error + 2 Error in plugin system + 3 Fatal deprecation encountered + 100 Normal exit, at least one test failed + 101 Normal exit, at least one test skipped but none failed + 172 Chef License not accepted ``` -Below are some examples of using `exec` with different test locations: +Below are some examples of using `exec` with different test LOCATIONS: Chef Automate: - -```ruby -inspec automate login -inspec exec compliance://username/linux-baseline -``` - -`inspec compliance` is a backwards compatible alias for `inspec automate` and works the same way: - -```ruby -inspec compliance login -``` + ``` + inspec automate login + inspec exec compliance://username/linux-baseline + ``` + `inspec compliance` is a backwards compatible alias for `inspec automate` and works the same way: + ``` + inspec compliance login + ``` Chef Supermarket: - -```ruby -inspec exec supermarket://username/linux-baseline -inspec exec supermarket://username/linux-baseline --supermarket_url="https://privatesupermarket.example.com" -``` + ``` + inspec exec supermarket://username/linux-baseline + ``` Local profile (executes all tests in `controls/`): + ``` + inspec exec /path/to/profile + ``` -```ruby -inspec exec /path/to/profile -``` +Local single test (doesn't allow inputs or custom resources) + ``` + inspec exec /path/to/a_test.rb + ``` -Local single test (doesn't allow inputs or custom resources): - -```ruby -inspec exec /path/to/a_test.rb -``` - -Git via SSH: - -```ruby -inspec exec git@github.com:dev-sec/linux-baseline.git -``` +Git via SSH + ``` + inspec exec git@github.com:dev-sec/linux-baseline.git + ``` Git via HTTPS (.git suffix is required): - -```ruby -inspec exec https://github.com/dev-sec/linux-baseline.git -``` + ``` + inspec exec https://github.com/dev-sec/linux-baseline.git + ``` Private Git via HTTPS (.git suffix is required): - -```ruby -inspec exec https://api_token@github.com/dev-sec/linux-baseline.git -``` + ``` + inspec exec https://API_TOKEN@github.com/dev-sec/linux-baseline.git + ``` Private Git via HTTPS and cached credentials (.git suffix is required): + ``` + git config credential.helper cache + git ls-remote https://github.com/dev-sec/linux-baseline.git + inspec exec https://github.com/dev-sec/linux-baseline.git + ``` -```bash -git config credential.helper cache -git ls-remote https://github.com/dev-sec/linux-baseline.git -inspec exec https://github.com/dev-sec/linux-baseline.git -``` +Web hosted file (also supports .zip): + ``` + inspec exec https://webserver/linux-baseline.tar.gz + ``` -Web-hosted file (also supports .zip): +Web hosted file with basic authentication (supports .zip): + ``` + inspec exec https://username:password@webserver/linux-baseline.tar.gz + ``` -```bash -inspec exec https://webserver/linux-baseline.tar.gz -``` - -Web-hosted file with basic authentication (supports .zip): - -```bash -inspec exec https://username:password@webserver/linux-baseline.tar.gz -``` ### Syntax @@ -289,140 +349,244 @@ inspec exec LOCATIONS This subcommand has the following additional options: -* `--attrs=one two three` - Legacy name for --input-file - deprecated. -* `--auto-install-gems` - Auto installs gem dependencies of the profile or resource pack. -* `-b`, `--backend=BACKEND` - Choose a backend: local, ssh, winrm, docker. -* `--backend-cache`, `--no-backend-cache` - Allow caching for backend command output. (default: true). -* `--bastion-host=BASTION_HOST` - Specifies the bastion host if applicable. -* `--bastion-port=BASTION_PORT` - Specifies the bastion port if applicable. -* `--bastion-user=BASTION_USER` - Specifies the bastion user if applicable. -* `--ca-trust-file=PATH_TO_CA_TRUST_FILE` - Specify CA certificate required for SSL authentication (WinRM). -* `--client-cert=PATH_TO_CLIENT_CERTIFICATE` - Specify client certificate required for SSL authentication (WinRM). -* `--client-key=PATH_TO_CLIENT_KEY` - Specify client key required with client certificate for SSL authentication (WinRM). -* `--client-key-pass=CLIENT_CERT_PASSWORD` - Specify client certificate password, if required for SSL authentication (WinRM). -* `--command-timeout=SECONDS` - Maximum seconds to allow a command to run. -* `--config=CONFIG` - Read configuration from the JSON file (`-` reads from stdin). -* `--controls=one two three` - A list of control names to run or a list of /regexes/ to match against control names. Ignore all other tests. -* `--create-lockfile`, `--no-create-lockfile` - Write out a lockfile based on this execution (unless one already exists). -* `--distinct-exit`, `--no-distinct-exit` - Exit with code 101 if any tests fail and 100 if any are skipped (default). If disabled, exit 0 on skips and 1 for failures. -* `--docker-url` - Provides path to Docker API endpoint (Docker). Defaults to unix:///var/run/docker.sock on Unix systems and tcp://localhost:2375 on Windows. -* `--enable-password=ENABLE_PASSWORD` - Password for enable mode on Cisco IOS devices. -* `--filter-empty-profiles`, `--no-filter-empty-profiles` - Filter empty profiles (profiles without controls) from the report. -* `--filter-waived-controls` - Do not execute waived controls in InSpec at all. Must use with --waiver-file. Ignores the `run` setting of the waiver file. -* `--host=HOST` - Specify a remote host which is tested. -* `--input=name1=value1 name2=value2` - Specify one or more inputs directly on the command line, as --input NAME=VALUE. Accepts single-quoted YAML and JSON structures. -* `--input-file=one two three` - Load one or more input files, a YAML file with values for the profile to use. -* `--insecure`, `--no-insecure` - Disable SSL verification on select targets. -* `-i`, `--key-files=one two three` - Login key or certificate file for a remote scan. -* `--password=PASSWORD` - Login password for a remote scan, if required. -* `--path=PATH` - Login path to use when connecting to the target (WinRM). -* `-p`, `--port=N` - Specify the login port for a remote scan. -* `--podman-url` - Provides the path to the Podman API endpoint. Defaults to unix:///run/user/$UID/podman/podman.sock for rootless container, unix:///run/podman/podman.sock for rootful container (for this you need to execute inspec as root user). -* `--profiles-path=PROFILES_PATH` - Folder which contains referenced profiles. -* `--proxy-command=PROXY_COMMAND` - Specifies the command to use to connect to the server. -* `--reporter=one two:/output/file/path` - Enable one or more output reporters: cli, documentation, html2, progress, progress-bar, json, json-min, json-rspec, junit2, yaml. -* `--reporter-backtrace-inclusion`, `--no-reporter-backtrace-inclusion` - Include a code backtrace in report data (default: true). -* `--reporter-include-source` - Include full source code of controls in the CLI report. -* `--reporter-message-truncation=REPORTER_MESSAGE_TRUNCATION` - Number of characters to truncate failure messages in report data (default: no truncation). -* `--self-signed`, `--no-self-signed` - Allow remote scans with self-signed certificates (WinRM). -* `--shell`, `--no-shell` - Run scans in a subshell. Only activates on Unix. -* `--shell-command=SHELL_COMMAND` - Specify a particular shell to use. -* `--shell-options=SHELL_OPTIONS` - Additional shell options. -* `--show-progress`, `--no-show-progress` - Show progress while executing tests. -* `--silence-deprecations=all|GROUP GROUP...` - Suppress deprecation warnings. See install_dir/etc/deprecations.json for a list of GROUPs or use 'all'. -* `--ssh-config-file=one two three` - A list of paths to the SSH configuration file, for example: `~/.ssh/config` or `/etc/ssh/ssh_config`. -* `--ssl`, `--no-ssl` - Use SSL for transport layer encryption (WinRM). -* `--ssl-peer-fingerprint` - Specify SSL peer fingerprint in place of certificates for SSL authentication (WinRM). -* `--sudo`, `--no-sudo` - Run scans with sudo. Only activates on Unix and non-root user. -* `--sudo-command=SUDO_COMMAND` - Alternate command for sudo. -* `--sudo-options=SUDO_OPTIONS` - Additional sudo options for a remote scan. -* `--sudo-password=SUDO_PASSWORD` - Specify a sudo password, if it is required. -* `-t`, `--target=TARGET` - Simple targeting option using URIs, e.g. ssh://user:pass@host:port. -* `--target-id=TARGET_ID` - Provide an ID that is included on reports - deprecated. -* `--tags=one two three` - A list of tags or regular expressions that match tags. `exec` will run controls referenced by the listed or matching tags. -* `--user=USER` - The login user for a remote scan. -* `--vendor-cache=VENDOR_CACHE` - Use the given path for caching dependencies. (default: `~/.inspec/cache`). -* `--waiver-file=one two three` - Load one or more waiver files. -* `--winrm-basic-auth-only`, `--no-winrm-basic-auth-only` - Whether to use basic authentication, defaults to false (WinRM). -* `--winrm-disable-sspi`, `--no-winrm-disable-sspi` - Whether to use disable sspi authentication, defaults to false (WinRM). -* `--winrm-transport=WINRM_TRANSPORT` - Specify which transport to use, defaults to negotiate (WinRM). -* `--enhanced-outcomes` - Includes enhanced outcome of controls in report data. -* `--attestation-file=one two three` - Loads one or more attestation files. Using this option, makes the `enhanced-outcomes` option true. +
+
--attrs=one two three
+
Legacy name for --input-file - deprecated.
-## habitat +
--auto-install-gems, --no-auto-install-gems
+
Auto installs gem dependencies of the profile or resource pack.
-Create a Chef Habitat package. +
-b, --backend=BACKEND
+
Choose a backend: local, ssh, winrm, docker.
+ +
--backend-cache, --no-backend-cache
+
Allow caching for backend command output. (default: true).
+ +
--bastion-host=BASTION_HOST
+
Specifies the bastion host if applicable.
+ +
--bastion-port=BASTION_PORT
+
Specifies the bastion port if applicable.
+ +
--bastion-user=BASTION_USER
+
Specifies the bastion user if applicable.
+ +
--ca-trust-file=CA_TRUST_FILE
+
Specify CA certificate required for SSL authentication (WinRM).
+ +
--client-cert=CLIENT_CERT
+
Specify client certificate for SSL authentication
+ +
--client-key=CLIENT_KEY
+
Specify client key required with client cert for SSL authentication
+ +
--client-key-pass=CLIENT_KEY_PASS
+
Specify client cert password, if required for SSL authentication
+ +
--command-timeout=N
+
Maximum seconds to allow commands to run during execution.
+ +
--config=CONFIG
+
Read configuration from JSON file (`-` reads from stdin).
+ +
--controls=one two three
+
A list of control names to run, or a list of /regexes/ to match against control names. Ignore all other tests.
+ +
--create-lockfile, --no-create-lockfile
+
Write out a lockfile based on this execution (unless one already exists)
+ +
--diff, --no-diff
+
Use --no-diff to suppress 'diff' output of failed textual test results.
+ +
--distinct-exit, --no-distinct-exit
+
Exit with code 101 if any tests fail, and 100 if any are skipped (default). If disabled, exit 0 on skips and 1 for failures.
+ +
--docker-url=DOCKER_URL
+
Provides path to Docker API endpoint (Docker). Defaults to unix:///var/run/docker.sock on Unix systems and tcp://localhost:2375 on Windows.
+ +
--enable-password=ENABLE_PASSWORD
+
Password for enable mode on Cisco IOS devices.
+ +
--enhanced-outcomes, --no-enhanced-outcomes
+
Show enhanced outcomes in output
+ +
--filter-empty-profiles, --no-filter-empty-profiles
+
Filter empty profiles (profiles without controls) from the report.
+ +
--filter-waived-controls, --no-filter-waived-controls
+
Do not execute waived controls in InSpec at all. Must use with --waiver-file. Ignores the `run` setting of the waiver file.
+ +
--host=HOST
+
Specify a remote host which is tested.
+ +
--input=name1=value1 name2=value2
+
Specify one or more inputs directly on the command line, as --input NAME=VALUE. Accepts single-quoted YAML and JSON structures.
+ +
--input-file=one two three
+
Load one or more input files, a YAML file with values for the profile to use.
+ +
--insecure, --no-insecure
+
Disable SSL verification on select targets.
+ +
-i, --key-files=one two three
+
Login key or certificate file for a remote scan.
+ +
--password=PASSWORD
+
Login password for a remote scan, if required.
+ +
--path=PATH
+
Login path to use when connecting to the target (WinRM).
+ +
--podman-url=PODMAN_URL
+
Provides the path to the Podman API endpoint. Defaults to unix:///run/user/$UID/podman/podman.sock for rootless container, unix:///run/podman/podman.sock for rootful container (for this you need to execute inspec as root user).
+ +
-p, --port=N
+
Specify the login port for a remote scan.
+ +
--profiles-path=PROFILES_PATH
+
Folder which contains referenced profiles.
+ +
--proxy-command=PROXY_COMMAND
+
Specifies the command to use to connect to the server.
+ +
--reporter=one two:/output/file/path
+
Enable one or more output reporters: cli, documentation, html, progress, progress-bar, json, json-min, json-rspec, junit, yaml
+ +
--reporter-backtrace-inclusion, --no-reporter-backtrace-inclusion
+
Include a code backtrace in report data (default: true)
+ +
--reporter-include-source, --no-reporter-include-source
+
Include full source code of controls in the CLI report
+ +
--reporter-message-truncation=REPORTER_MESSAGE_TRUNCATION
+
Number of characters to truncate failure messages and code_desc in report data to (default: no truncation)
+ +
--retain-waiver-data, --no-retain-waiver-data
+
EXPERIMENTAL: Only works in conjunction with --filter-waived-controls, retains waiver data about controls that were skipped
+ +
--self-signed, --no-self-signed
+
Allow remote scans with self-signed certificates (WinRM).
+ +
--shell, --no-shell
+
Run scans in a subshell. Only activates on Unix.
+ +
--shell-command=SHELL_COMMAND
+
Specify a particular shell to use.
+ +
--shell-options=SHELL_OPTIONS
+
Additional shell options.
+ +
--show-progress, --no-show-progress
+
Show progress while executing tests.
+ +
--silence-deprecations=all|GROUP GROUP...
+
Suppress deprecation warnings. See install_dir/etc/deprecations.json for a list of GROUPs or use 'all'.
+ +
--sort-results-by=--sort-results-by=none|control|file|random
+
After normal execution order, results are sorted by control ID, or by file (default), or randomly. None uses legacy unsorted mode.
+ +
--ssh-config-file=one two three
+
A list of paths to the ssh config file, e.g ~/.ssh/config or /etc/ssh/ssh_config.
+ +
--ssl, --no-ssl
+
Use SSL for transport layer encryption (WinRM).
+ +
--ssl-peer-fingerprint=SSL_PEER_FINGERPRINT
+
Specify SSL peer fingerprint in place of certificates for SSL authentication (WinRM).
+ +
--sudo, --no-sudo
+
Run scans with sudo. Only activates on Unix and non-root user.
+ +
--sudo-command=SUDO_COMMAND
+
Alternate command for sudo.
+ +
--sudo-options=SUDO_OPTIONS
+
Additional sudo options for a remote scan.
+ +
--sudo-password=SUDO_PASSWORD
+
Specify a sudo password, if it is required.
+ +
--supermarket-url=SUPERMARKET_URL
+
Specify the URL of a private Chef Supermarket.
+ +
--tags=one two three
+
A list of tags names that are part of controls to filter and run controls, or a list of /regexes/ to match against tags names of controls. Ignore all other tests.
+ +
-t, --target=TARGET
+
Simple targeting option using URIs, e.g. ssh://user:pass@host:port
+ +
--target-id=TARGET_ID
+
Provide an ID which will be included on reports - deprecated
+ +
--user=USER
+
The login user for a remote scan.
+ +
--vendor-cache=VENDOR_CACHE
+
Use the given path for caching dependencies, (default: ~/.inspec/cache).
+ +
--waiver-file=one two three
+
Load one or more waiver files.
+ +
--winrm-basic-auth-only, --no-winrm-basic-auth-only
+
Whether to use basic authentication, defaults to false (WinRM).
+ +
--winrm-disable-sspi, --no-winrm-disable-sspi
+
Whether to use disable sspi authentication, defaults to false (WinRM).
+ +
--winrm-shell-type=WINRM_SHELL_TYPE
+
Specify which shell type to use (powershell, elevated, or cmd), which defaults to powershell (WinRM).
+ +
--winrm-transport=WINRM_TRANSPORT
+
Specify which transport to use, defaults to negotiate (WinRM).
+ +
+ +## export + +Read the profile in path and generate a summary in the given format. ### Syntax This subcommand has the following syntax: ```bash -inspec habitat SUBCOMMAND +inspec export PATH ``` +### Options + +This subcommand has the following additional options: + +
+
--auto-install-gems, --no-auto-install-gems
+
Auto installs gem dependencies of the profile or resource pack.
+ +
--controls=one two three
+
For --what=profile, a list of controls to include. Ignore all other tests.
+ +
--format=FORMAT
+
The output format to use: json, raw, yaml. If valid format is not provided then it will use the default for the given 'what'.
+ +
-o, --output=OUTPUT
+
Save the created output to a path.
+ +
--profiles-path=PROFILES_PATH
+
Folder which contains referenced profiles.
+ +
--tags=one two three
+
For --what=profile, a list of tags to filter controls and include only those. Ignore all other tests.
+ +
--vendor-cache=VENDOR_CACHE
+
Use the given path for caching dependencies, (default: ~/.inspec/cache).
+ +
--what=WHAT
+
What to export: profile (default), readme, metadata.
+ +
+ ## help -Describe available commands or one specific command. +Describe available commands or one specific command ### Syntax @@ -432,18 +596,6 @@ This subcommand has the following syntax: inspec help [COMMAND] ``` -## init - -Scaffold a new project. - -### Syntax - -This subcommand has the following syntax: - -```bash -inspec init TEMPLATE -``` - ## json Read all tests in the path and generate a json summary. @@ -460,44 +612,42 @@ inspec json PATH This subcommand has the following additional options: -* `--controls=one two three` - A list of controls to include. Ignore all other tests. -* `-o`, `--output=OUTPUT` - Save the created profile to a path. -* `--profiles-path=PROFILES_PATH` - Folder which contains referenced profiles. -* `--tags=one two three` - A list of tags that reference specific controls. Other controls are ignored. -* `--vendor-cache=VENDOR_CACHE` - Use the given path for caching dependencies. (default: `~/.inspec/cache`). +
+
--auto-install-gems, --no-auto-install-gems
+
Auto installs gem dependencies of the profile or resource pack.
-## nothing +
--controls=one two three
+
A list of controls to include. Ignore all other tests.
-Does nothing. +
-o, --output=OUTPUT
+
Save the created profile to a path.
+ +
--profiles-path=PROFILES_PATH
+
Folder which contains referenced profiles.
+ +
--tags=one two three
+
A list of tags to filter controls and include only those. Ignore all other tests.
+ +
--vendor-cache=VENDOR_CACHE
+
Use the given path for caching dependencies, (default: ~/.inspec/cache).
+ +
+ +## run_context + +Used to test run-context detection ### Syntax This subcommand has the following syntax: ```bash -inspec nothing -``` - -## plugin - -Install and manage [Chef InSpec plugins](/inspec/plugins/). - -### Syntax - -This subcommand has the following syntax: - -```bash -inspec plugin SUBCOMMAND +inspec run_context ``` ## schema -Print the json schema. +Print the json schema ### Syntax @@ -509,10 +659,13 @@ inspec schema NAME ### Options -This subcommand has the following additional option: +This subcommand has the following additional options: -* `--enhanced-outcomes` - Includes enhanced outcome of controls in report data. +
+
--enhanced-outcomes, --no-enhanced-outcomes
+
Show enhanced outcomes output
+ +
## shell @@ -530,96 +683,150 @@ inspec shell This subcommand has the following additional options: -* `-b`, `--backend=BACKEND` - Choose a backend: local, ssh, winrm, docker. -* `--bastion-host=BASTION_HOST` - Specifies the bastion host if applicable. -* `--bastion-port=BASTION_PORT` - Specifies the bastion port if applicable. -* `--bastion-user=BASTION_USER` - Specifies the bastion user if applicable. -* `-c`, `--command=COMMAND` - A single command string to run instead of launching the shell. -* `--command-timeout=SECONDS` - Maximum seconds to allow a command to run. -* `--ca-trust-file=PATH_TO_CA_TRUST_FILE` - Specify CA certificate required for SSL authentication (WinRM). -* `--client-cert=PATH_TO_CLIENT_CERTIFICATE` - Specify client certificate required for SSL authentication (WinRM). -* `--client-key=PATH_TO_CLIENT_KEY` - Specify client key required with client certificate for SSL authentication (WinRM). -* `--client-key-pass=CLIENT_CERT_PASSWORD` - Specify client certificate password, if required for SSL authentication (WinRM). -* `--config=CONFIG` - Read configuration from the JSON file (`-` reads from stdin). -* `--depends=one two three` - A space-delimited list of local folders containing profiles whose libraries and resources will be loaded into the new shell. -* `--distinct-exit`, `--no-distinct-exit` - Exit with code 100 if any tests fail and 101 if any are skipped, but none failed (default). If disabled, exit 0 on skips and 1 for failures. -* `--docker-url` - Provides path to Docker API endpoint (Docker). Defaults to unix:///var/run/docker.sock on Unix systems and tcp://localhost:2375 on Windows. -* `--enable-password=ENABLE_PASSWORD` - Password for enable mode on Cisco IOS devices. -* `--host=HOST` - Specify a remote host which is tested. -* `--insecure`, `--no-insecure` - Disable SSL verification on select targets. -* `--inspect`, `--no-inspect` - Use verbose/debugging output for resources. -* `-i`, `--key-files=one two three` - Login key or certificate file for a remote scan. -* `--password=PASSWORD` - Login password for a remote scan, if required. -* `--path=PATH` - Login path to use when connecting to the target (WinRM). -* `-p`, `--port=N` - Specify the login port for a remote scan. -* `--podman-url` - Provides the path to the Podman API endpoint. Defaults to unix:///run/user/$UID/podman/podman.sock for rootless container, unix:///run/podman/podman.sock for rootful container (for this you need to execute inspec as root user). -* `--proxy-command=PROXY_COMMAND` - Specifies the command to use to connect to the server. -* `--reporter=one two:/output/file/path` - Enable one or more output reporters: cli, documentation, html2, progress, json, json-min, json-rspec, junit2. -* `--self-signed`, `--no-self-signed` - Allow remote scans with self-signed certificates (WinRM). -* `--shell`, `--no-shell` - Run scans in a subshell. Only activates on Unix. -* `--shell-command=SHELL_COMMAND` - Specify a particular shell to use. -* `--shell-options=SHELL_OPTIONS` - Additional shell options. -* `--ssh-config-file=one two three` - A list of paths to the SSH configuration file, for example: `~/.ssh/config` or `/etc/ssh/ssh_config`. -* `--ssl`, `--no-ssl` - Use SSL for transport layer encryption (WinRM). -* `--ssl-peer-fingerprint=SSL_PEER_FINGERPRINT` - Specify SSL peer fingerprint in place of certificates for SSL authentication (WinRM). -* `--sudo`, `--no-sudo` - Run scans with sudo. Only activates on Unix and non-root user. -* `--sudo-command=SUDO_COMMAND` - Alternate command for sudo. -* `--sudo-options=SUDO_OPTIONS` - Additional sudo options for a remote scan. -* `--sudo-password=SUDO_PASSWORD` - Specify a sudo password, if it is required. -* `-t`, `--target=TARGET` - Simple targeting option using URIs, e.g. ssh://user:pass@host:port. -* `--target-id=TARGET_ID` - Provide a ID which will be included on reports. -* `--user=USER` - The login user for a remote scan. -* `--winrm-basic-auth-only`, `--no-winrm-basic-auth-only` - Whether to use basic authentication, defaults to false (WinRM). -* `--winrm-disable-sspi`, `--no-winrm-disable-sspi` - Whether to use disable sspi authentication, defaults to false (WinRM). -* `--winrm-transport=WINRM_TRANSPORT` - Specify which transport to use, defaults to negotiate (WinRM). -* `--enhanced-outcomes` - Includes enhanced outcome of controls in report data. +
+
-b, --backend=BACKEND
+
Choose a backend: local, ssh, winrm, docker.
+ +
--bastion-host=BASTION_HOST
+
Specifies the bastion host if applicable.
+ +
--bastion-port=BASTION_PORT
+
Specifies the bastion port if applicable.
+ +
--bastion-user=BASTION_USER
+
Specifies the bastion user if applicable.
+ +
--ca-trust-file=CA_TRUST_FILE
+
Specify CA certificate required for SSL authentication (WinRM).
+ +
--client-cert=CLIENT_CERT
+
Specify client certificate for SSL authentication
+ +
--client-key=CLIENT_KEY
+
Specify client key required with client cert for SSL authentication
+ +
--client-key-pass=CLIENT_KEY_PASS
+
Specify client cert password, if required for SSL authentication
+ +
-c, --command=COMMAND
+
A single command string to run instead of launching the shell
+ +
--command-timeout=N
+
Maximum seconds to allow a command to run.
+ +
--config=CONFIG
+
Read configuration from JSON file (`-` reads from stdin).
+ +
--depends=one two three
+
A space-delimited list of local folders containing profiles whose libraries and resources will be loaded into the new shell
+ +
--distinct-exit, --no-distinct-exit
+
Exit with code 100 if any tests fail, and 101 if any are skipped but none failed (default). If disabled, exit 0 on skips and 1 for failures.
+ +
--docker-url=DOCKER_URL
+
Provides path to Docker API endpoint (Docker). Defaults to unix:///var/run/docker.sock on Unix systems and tcp://localhost:2375 on Windows.
+ +
--enable-password=ENABLE_PASSWORD
+
Password for enable mode on Cisco IOS devices.
+ +
--enhanced-outcomes, --no-enhanced-outcomes
+
Show enhanced outcomes in output
+ +
--host=HOST
+
Specify a remote host which is tested.
+ +
--input=name1=value1 name2=value2
+
Specify one or more inputs directly on the command line to the shell, as --input NAME=VALUE. Accepts single-quoted YAML and JSON structures.
+ +
--input-file=one two three
+
Load one or more input files, a YAML file with values for the shell to use
+ +
--insecure, --no-insecure
+
Disable SSL verification on select targets.
+ +
--inspect, --no-inspect
+
Use verbose/debugging output for resources.
+ +
-i, --key-files=one two three
+
Login key or certificate file for a remote scan.
+ +
--password=PASSWORD
+
Login password for a remote scan, if required.
+ +
--path=PATH
+
Login path to use when connecting to the target (WinRM).
+ +
--podman-url=PODMAN_URL
+
Provides the path to the Podman API endpoint. Defaults to unix:///run/user/$UID/podman/podman.sock for rootless container, unix:///run/podman/podman.sock for rootful container (for this you need to execute inspec as root user).
+ +
-p, --port=N
+
Specify the login port for a remote scan.
+ +
--proxy-command=PROXY_COMMAND
+
Specifies the command to use to connect to the server.
+ +
--reporter=one two:/output/file/path
+
Enable one or more output reporters: cli, documentation, html, progress, json, json-min, json-rspec, junit
+ +
--self-signed, --no-self-signed
+
Allow remote scans with self-signed certificates (WinRM).
+ +
--shell, --no-shell
+
Run scans in a subshell. Only activates on Unix.
+ +
--shell-command=SHELL_COMMAND
+
Specify a particular shell to use.
+ +
--shell-options=SHELL_OPTIONS
+
Additional shell options.
+ +
--ssh-config-file=one two three
+
A list of paths to the ssh config file, e.g ~/.ssh/config or /etc/ssh/ssh_config.
+ +
--ssl, --no-ssl
+
Use SSL for transport layer encryption (WinRM).
+ +
--ssl-peer-fingerprint=SSL_PEER_FINGERPRINT
+
Specify SSL peer fingerprint in place of certificates for SSL authentication (WinRM).
+ +
--sudo, --no-sudo
+
Run scans with sudo. Only activates on Unix and non-root user.
+ +
--sudo-command=SUDO_COMMAND
+
Alternate command for sudo.
+ +
--sudo-options=SUDO_OPTIONS
+
Additional sudo options for a remote scan.
+ +
--sudo-password=SUDO_PASSWORD
+
Specify a sudo password, if it is required.
+ +
-t, --target=TARGET
+
Simple targeting option using URIs, e.g. ssh://user:pass@host:port
+ +
--target-id=TARGET_ID
+
Provide an ID which will be included on reports - deprecated
+ +
--user=USER
+
The login user for a remote scan.
+ +
--winrm-basic-auth-only, --no-winrm-basic-auth-only
+
Whether to use basic authentication, defaults to false (WinRM).
+ +
--winrm-disable-sspi, --no-winrm-disable-sspi
+
Whether to use disable sspi authentication, defaults to false (WinRM).
+ +
--winrm-shell-type=WINRM_SHELL_TYPE
+
Specify which shell type to use (powershell, elevated, or cmd), which defaults to powershell (WinRM).
+ +
--winrm-transport=WINRM_TRANSPORT
+
Specify which transport to use, defaults to negotiate (WinRM).
+ +
## supermarket -Supermarket commands. +Supermarket commands ### Syntax @@ -629,16 +836,9 @@ This subcommand has the following syntax: inspec supermarket SUBCOMMAND ... ``` -### Options - -This subcommand has additional options: - -* `--supermarket_url` - Specify the URL of a private Chef Supermarket. - ## vendor -Download all dependencies and generate a lockfile in a `vendor` directory. +Download all dependencies and generate a lockfile in a `vendor` directory ### Syntax @@ -650,10 +850,13 @@ inspec vendor PATH ### Options -This subcommand has additional options: +This subcommand has the following additional options: -* `--overwrite`, `--no-overwrite` - Overwrite existing vendored dependencies and lockfiles. +
+
--overwrite, --no-overwrite
+
Overwrite existing vendored dependencies and lockfile.
+ +
## version @@ -671,4 +874,6 @@ inspec version This subcommand has the following additional options: -* `--format=FORMAT` +
+
--format=FORMAT
+
diff --git a/tasks/docs.rb b/tasks/docs.rb index 52f8fe081..5fd1235a2 100644 --- a/tasks/docs.rb +++ b/tasks/docs.rb @@ -14,10 +14,7 @@ # limitations under the License. # -require "erb" require "fileutils" -require "yaml" -require "git" DOCS_DIR = "docs-chef-io/content/inspec".freeze @@ -62,7 +59,7 @@ class Markdown end def dl(msg) - "#{msg.gsub("\n", "\n ")}\n" + "
\n#{msg}
\n\n" end def ul(msg) @@ -180,12 +177,12 @@ namespace :docs do # rubocop:disable Metrics/BlockLength usage = opt.usage.split(", ") .map { |x| x.tr("[]", "") } .map { |x| x.start_with?("-") ? x : "-" + x } - .map { |x| "`" + x + "`" } - msg = "#{usage.join(", ")}\n" - msg << ": #{opt.description}\n" if opt.description && !opt.description.empty? - list << f.dl(msg) + .map { |x| "" + x + "" } + msg = "
#{usage.join(", ")}
\n" + msg << "
#{opt.description}
\n\n" if opt.description && !opt.description.empty? + list << msg end.join - res << f.ul(list) + res << f.dl(list) end # FIXME: for some reason we have extra lines in our RST; needs investigation