Using Steampunk Scanner's Command Line Interface (CLI)

WORDS BY Tadej Borovšak

Almost exactly five months ago, we unveiled the first version of Steampunk Scanner. To keep things simple, we only offered an online version at that time. The initial version took an Ansible playbook as input and returned some suggestions on how to improve your content.

But that web page also contained another critical section: the feedback form. And we did not put it there just for fun because we all know dealing with any web form is by definition not fun ;) We read what you had to say and decided to implement the most requested feature.

Can you guess what it was?

Scanning content from command-line

We knew right from the get-go that Steampunk Scanner would need the command-line interface (CLI) because, let us face it, pasting playbooks into a web form does not scale. Also, there are not too many developers who use the text field on a web page as their text editor ;)

Once we install the steampunk-scanner Python package and register our email address with the service, we are ready to start scanning.

Why do we require registration? Steampunk Scanner is a service that we host, and we cannot afford to be bombarded with gazillions of unauthenticated requests from anyone who has three minutes of spare time. So, to reduce the malicious load on the API while still making it as widely accessible as possible, we decided to put it behind basic authentication. And we need your email address because we need to send you an activation code for your account.

To start checking playbooks straight from the terminal, we should run the following command:

$ steampunk-scanner --playbooks playbook.yaml

What we can get back will look something like this:

playbook.yaml:10: ERROR: Cannot find module information in the database. Is
  this a custom module not published on Ansible Galaxy?
playbook.yaml:14: HINT: Module is deprecated. os_ prefixed module names are
  deprecated, use openstack.cloud.compute_flavor_info.
playbook.yaml:14: HINT: The 'openstack.cloud.os_flavor_info' module is
  redirected to the 'openstack.cloud.compute_flavor_info' module. You should
  use fully-qualified collection name to avoid future problems.
playbook.yaml:14: WARNING: The 'openstack.cloud.os_flavor_info' module is not
  certified.

And if you get back nothing? Well, good for you. We found no issues with your playbook ;)

Although we run the scanner on our local machine, checking still happens on the same server that backs the online checker. The CLI application locally parses your content and then sends the following data to the backend service about each task:

1. the module name used by the Ansible task, and
2. parameter names that the current playbook task uses.

Do note that we do not send any parameter values to the backend. We will need to send more data to the backend in the future when we add more checks, but we err on the safe side for now and send as little information as possible.

So, this is it. Or is it? ;)

Going beyond Ansible playbooks

Another quite common complaint (mostly coming from our sysadmin team, bless their gentle souls) was the lack of support for other kinds of Ansible content. And as much as we like to ignore them, we had to admit that they do have a point here ;)

So the Steampunk Scanner CLI supports scanning:

1. Ansible playbooks - steampunk-scanner --playbooks play.yaml.
2. Ansible roles - steampunk-scanner --roles role/dir.
3. Ansible task files - steampunk-scanner --tasks tasks/file.yaml.
4. Ansible collections - steampunk-scanner --collections collection/root.

Supporting all those different content types should cover a majority of scenarios where the scanner has its use. But, of course, we can also mix and match those command-line switched[KT4][TB5] to our heart’s delight. Nothing is preventing us from scanning playbooks, tasks, roles, and collections at the same time.

And while we were adding things, we also made it possible to analyze content in bulk. For example, running steampunk-scanner --roles my/roles/* will examine all roles in the my/roles directory. You are welcome ;)

The future

So, what do we have in the plan next? We will definitely be adding more checks, a friendly dashboard that will allow you to see the results of scans, and integrations with CI processes. Sounds good? Is there anything else you think we should be adding? What features do you think would come in handy to simplify your playbook writing? Share your thoughts and wishes with us and stay tuned for more. Oh, and also, feel free to use the brand new command-line interface.

Cheers!