dsms_cli 1.1.8

DSMS CLI tool
--------------------

dsms_cli is a command line interface for exporting reports from a DSMS
system.

============
Installation
============

``pip install dsms-cli``

========
Setup
========

Before you'll begin, you'll need several settings set as environment variables:

* DSMS_SERVER (e.g. https://mydsmsserver)
* DSMS_USER (e.g. tom)
* DSMS_PASS (e.g. ThisIsMyPassword)
* DSMS_SERVER_CERT (optional: e.g. /usr/share/ca-certificates/dsmserver.crt)

=========
Adding targets
=========

To add targets, you'll firstly need the ID numbers of the schedules, profiles
and severities you wish to add. You can do this with::

dsms_cli list schedules
dsms_cli list profiles
dsms_cli list severities

Then, you're ready to add targets. For example::

dsms_cli add location --profile=1 --schedule=1 http://example.com
dsms_cli add file --profile=2 --schedule=1 mysample.exe

For file types, the local file path you specify will be uploaded to DSMS.

=========
Running reports
=========


You can also run searches of DSMS results using the same filter syntax as the
web application. For example, to get all active phishing targets, run::

dsms_cli export --query="status:Active type:Phishing"

You can also redact potentially sensitive information in target information
by supplying the --redact switch. This will replace URLs like
http://example.com/?id=me@example.com with
http://example.com/?id=REDACTED@REDACTED.

=========
Report formats
=========

DSMS has a simple build-in report template, but you may create templates in any
format you like. Reports are generated by the Jinja2 template engine. See
http://jinja.pocoo.org/docs/dev/templates/ for details of the format.

If you'd like to add report formats:

1) Create a directory to house your templates, e.g. $HOME/dsms_templates.
2) Create your template using the .j2 extension, e.g.
$HOME/dsms_templates/my_format.j2.
3) Templates must adhere to Jinja2 format. You can find a simple example of
the DSMS standard template at
https://gist.github.com/chorsley/d52f8e8bf3c6df4901b38ed316af5889.
4) Variable names map to the API fields for "Target filter report" under
the "results" key. Please see
https://bitbucket.org/irtools/dsms/wiki/UsingDSMSAPI for more information.
5) Finally, run the report. Using our example values:
``dsms_cli export --template_dir=$HOME/dsms_templates --template=my_format``.
Naturally, you can combine this with --query, --redact etc to filter the
targets that will appear in the report.

=========
SSL errors
=========

If you're using DSMS with a self-signed SSL certificate, you may run into the
following error::

RuntimeError: Error during login: bad handshake: Error([('SSL routines',
'SSL3_GET_SERVER_CERTIFICATE', 'certificate verify failed')],)

There are two options to avoid this.

1) You can specify the path to a trusted SSL certificate using the
DSMS_SERVER_CERT environment setting. To get this cert, you can run::

openssl s_client -showcerts -connect [YOUR DSMS HOST]:443 </dev/null \
2>/dev/null|openssl x509 -outform PEM >dsms_server_cert.crt

Then, set the cert path to the file you downloaded::

export DSMS_SERVER_CERT=dsms_server_cert.crt

2) While not recommended, you can also ignore all SSL errors by appending
--ignore_ssl_errs to your dsms_cli command.

=========
Further help
=========

To see all command line switches, you can run::

dsms_cli --help