dsms_cli 1.1.5

DSMS CLI tool

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=[e-mail] with
http://example.com/?id=REDACTED@REDACTED.

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

Reports are generated by Jinja2 templates. If you'd like to add new types of
reports, you can place these in a separate directory and tell dsms_report where
to find these using ``dsms_cli export --template_dir=[your custom templates]``.

=========
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