Ansible Playbook Scanning Tool
Project description
Steampunk Spotter Command-Line Interface (CLI)
Steampunk Spotter provides an Ansible Playbook Scanning Tool that analyzes and offers recommendations for your Ansible Playbooks.
The Steampunk Spotter CLI enables the use from the console with the ability to scan Ansible content such as playbooks, roles, collections, or task files.
The following instructions explain how to get started with the Steampunk Spotter CLI to scan Ansible content and get recommendations.
Installation
Steampunk Spotter CLI requires Python 3 and is available as a steampunk-spotter Python package.
$ pip install steampunk-spotter
We recommend installing the package into a clean Python virtual environment.
Usage
After the CLI is installed, you can explore its commands and options by
running spotter --help
.
The --help/-h
optional argument is also available for every command.
Limitations
The current release version of Steampunk Spotter contains the following limitations that also apply to the CLI:
- with the FREE subscription plan, you can perform up to 100 scans/month,
- with the INDIVIDUAL, TEAM, or ENTERPRISE subscription plan you can perform an unlimited number of scans,
- for the ENTERPRISE subscription plan, contact us at steampunk@xlab.si to discuss your needs.
Authentication
To use CLI, you have to supply your Steampunk Spotter user account credentials.
If you don't have an account, use spotter register
command that will direct
you to the page where you can create one.
Steampunk Spotter supports two kinds of credentials: 1) API token (can be generated in the user settings within the Spotter App), and 2) username and password.
- Use
--api-token/-t
global optional argument to supply your token credential. Alternatively, set theSPOTTER_API_TOKEN
environment variable to contain the API token. - Use
--username/-u
and--password/-p
global optional arguments to supply your username ad password. Alternatively, set theSPOTTER_USERNAME
andSPOTTER_PASSWORD
environment variables. - You can run
spotter <options> login
to persist your credentials in the Steampunk Spotter CLI's local storage, where<options>
stand for one of the approaches described above.
After that, you can start scanning right away.
Scanning
The CLI spotter scan
command is used for scanning Ansible
content (playbooks, roles, collections, or task files) and returning the
scan results.
Ansible content
The scan
command will automatically detect the type of your Ansible content
and scan it.
Here are some examples of running scans:
# scan playbook
$ spotter scan path/to/playbook.yaml
# scan multiple files at once
$ spotter scan path/to/taskfile.yaml \
path/to/playbook.yaml \
path/to/role \
path/to/collection
# scan any folder that contains Ansible content
$ spotter scan path/to/folder
Selecting the target project
This part is only relevant for users with a TEAM plan or higher.
By default, the scan results are stored in the first project of the user's first organization (in the app).
Users that have multiple organizations or projects in the app can use
--project-id
optional argument to specify the UUID of an existing target
project, where the scan result will be stored.
$ spotter scan --project-id <project-id> .
You can learn your project id by logging into the app, selecting the appropriate organization and navigating to the project's dashboard.
Excluding values
By default, CLI parses full Ansible YAML content with all values from
playbooks (e.g., parameter values from Ansible modules,
variables from Ansible plays, etc.).
With values, we can discover additional tips for improvements.
CLI will try to detect and omit any secrets (e.g., passwords, SSH keys,
cloud credentials, etc.) from being transmitted.
If you want to omit parsing and sending the values, you can use
--exclude-values
optional argument.
$ spotter scan --exclude-values playbook.yaml
Excluding metadata
By default, CLI collects metadata (i.e., file names, line, and column numbers,
YAML markers) from Ansible content.
This is needed for enriched user experience in the Spotter App and to get
additional tips for improvements.
If you want to use metadata just for displaying the scan output, which means
that no data about your Ansible content structure is sent to the backend
server, you can use --exclude-metadata
optional argument.
$ spotter scan --exclude-metadata playbook.yaml
Automated application of suggestions to your code
There is also a --rewrite
optional argument that rewrites your files with
fixes after scanning.
This action will modify your files.
$ spotter scan --rewrite playbook.yaml
Next steps
For more comprehensive usage, issue spotter scan --help
.
Please refer to DOCUMENTATION.md for further instructions.
Acknowledgment
This tool was created by XLAB Steampunk, IT automation specialists and leading experts in building Enterprise Ansible Collections.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
Hashes for steampunk_spotter-2.4.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a7f8f89ec458772fefbf5894fb09fa796fc185b7e6a651540946352c5eafc3fa |
|
MD5 | d7193df48b03e90f35aae06577dcfbb0 |
|
BLAKE2b-256 | 5e136a7e692aff8534dd0b39306c5f94e95bc5189d703d1b87fe99c0a0313ee8 |