Command line interface
When hansken.py is installed successfully, a hansken command will be available on the system’s path.
Examples used here often show lines starting with a $, this refers to the command line’s prompt and may look different on your system.
Commands available to the hansken.py command line can be listed by adding --help to the invocation of the hansken executable:
$ hansken --help
usage: hansken [-h] [--version] COMMAND ...
positional arguments:
COMMAND
quickstart
interactively determine configuration values for use with
hansken.py
shell spawn an interactive python shell
... (more available commands)
optional arguments:
-h, --help show this help message and exit
--version show program's version number and exit
Additionally, all commands supported by hansken.py explain their command line arguments when --help is supplied after a command:
$ hansken shell --help
usage: hansken shell [-h] [-v] [-l FILE] [-e ENDPOINT] [--keystore ENDPOINT]
[--idp IDP_ID] [-u USER] [-p PROJECT] [-a]
optional arguments:
-p PROJECT, --project PROJECT
attach to project with id PROJECT (defaults to
environment variable HANSKEN_PROJECT)
... (more optional arguments)
Todo
Parameters always parsed (endpoints, logging, …)
Environment values
Todo
HANSKEN_ENDPOINT— Hansken HTTP REST urlHANSKEN_KEYSTORE_ENDPOINT— Hansken keystore HTTP REST urlHANSKEN_PROJECT— Project identifier (only used byhansken shell)HANSKEN_IDP— Identity provider ‘name’ (can be anything, see authentication)HANSKEN_LOG— File name to append logging to
User commands
hansken quickstart
Command to generate a starting point for other commands or scripts.
hansken.py will interactively ask you for values it needs or ask you to choose between options.
The result of this is a set of command line arguments that can be saved to a file.
This ‘argfile’ can then be included with any invocation of hansken or hansken.py-powered scripts on the command line:
$ hansken quickstart
... (answer questions, make choices)
# a REST endpoint to communicate with
--endpoint https://hansken.example.nl/gatekeeper
# name of the identity provider to authenticate to
--idp example.nl/openam
# a REST endpoint to retrieve keys from
--keystore https://hansken.example.nl/keystore
After saving the content printed by the command to a file named example.args, it can be included with any command or script as such:
$ hansken versions @example.args
$ python3 script.py @example.args
hansken shell
Command to interactively explore hansken.py objects.
Given a configuration file as generated with hansken quickstart, start an interactive shell as such:
$ hansken shell @example.args
... (information about your python version)
... (information about ipython)
Hansken interactive shell (client API version 2017.01.16)
connection -> <hansken.remote.Connection endpoint=... (your configured hansken endpoint)>
In [1]:
The interactive shell works much like invoking python without arguments on the command line, executing entered lines as Python code.
With just the configuration as generated by hansken quickstart, the shell as shown above will provide a Connection object to play with.
Using the -p / --project argument on the command line, hansken shell will also create a ProjectContext:
$ hansken shell @example.args --project deadbeef-c0de-c0de-c0de-badbadc0ffee
... (pieces of information)
Hansken interactive shell (client API version 2017.01.16)
connection -> <hansken.remote.Connection endpoint=... (your configured hansken endpoint)>
context -> <hansken.remote.ProjectContext project_id=deadbeef-c0de-c0de-c0de-badbadc0ffee>
In [1]:
Python’s standard function help works as expected in this shell and will show information about objects,
including the documentation hansken.py provides for its objects.
hansken stats
hansken versions
Informational command showing the versions of hansken.py and the REST endpoint it’s communicating with.
If provided with a project id, output will include versions build numbers of Hansken at time of extraction for each image linked to the project.
Switches optionally include the raw data size of an image in human-readable form and the number of traces extracted from the images, for example:
$ hansken versions --size deadbeef-c0de-c0de-c0de-badbadc0ffee
hansken.py: 2016.02.23
REST endpoint: 1234-master (built on 2016-02-22)
id description version date size
------------------------------------ ----------------- ----------- ---------- ---------
12345678-0001-0000-0000-000000000001 Laptop Computer 1122-master 2016-01-04 109 GiB
12345678-0002-0000-0000-000000000001 My First SIM Card 1234-master 2016-02-22 1.833 MiB
The versions command allows the table above to be formatted in a number of ways using the Python module tabulate.
hansken mount
Command to make images linked to a project available as local files. Images are made available as files named after their image ids within the provided mount point. Symlinks using the image descriptions/names as the link names are added linking to their respective images.
Note
hansken mount uses FUSE and is only available when python module fusepy is installed.
FUSE itself requires some configuration, adding your local user to the fuse group being the most beneficial.
See FUSE documentation (and man pages) for mount options (accepted by hansken mount as -o/--options) and additional configuration.
An example invocation of hansken mount might look like this:
$ hansken mount -o uid=1000,allow_other deadbeef-c0de-c0de-c0de-badbadc0ffee /mnt
$ ls -lh /mnt
lr-xr-xr-x 0 example root 109G Apr 1 16:35 Laptop Computer -> 12345678-0001-0000-0000-000000000001
-r--r--r-- 0 example root 109G Apr 1 16:35 12345678-0001-0000-0000-000000000001
lr-xr-xr-x 0 example root 1.8M Feb 22 12:34 My First SIM Card -> 12345678-0002-0000-0000-000000000001
-r--r--r-- 0 example root 1.8M Feb 22 12:34 12345678-0002-0000-0000-000000000001
Note that the mount options passed as -o/--options are transparently passed to FUSE.
The full list of mount options (either system defaults, inserted by hansken.py or passed on the command line) will show up the output of the system command mount.
Note
The system might disallow unmounting of a filesystem by anyone other than root.
If this causes problems, use command line switch -f/--foreground, see hansken mount --help.
Terminating the foreground process using a keyboard interrupt will unmount the filesystem.
Administrative commands
hansken extract
hansken tools
Informational command listing the tools available for extraction in the Hansken back end. Output includes current registered versions for all tools and their descriptions (… inserted here for readability):
$ hansken tools
name version description
---------------------- --------------------------------------- -------------------------------------------------------------------------------
carve/gzip 1.1 Tool to carve for Gzip compressed content.
carve/html 1.0 Carves for HTML documents
…
data/digest/sha1 0.1 Data processor to hash / digest streams, using sha1
data/digest/sha256 0.1 Data processor to hash / digest streams, using sha256
…
Output can be formatted in a number of ways using the Python module tabulate.
hansken tasks
Informational command listing either open or closed tasks tracked by the Hansken scheduler:
$ hansken tasks --from 2018-08-20
id type project status since
------------------------------------ ------- ------------------------------------ -------- ------------------------
084a8b66-74fe-425f-a59e-dd8ea1fac4e6 extract 021b48f6-effe-4ae5-beaa-85f1e6b1d60d running 2018-08-23T14:12:54.191Z
hansken upload
hansken backup
Command for initiating a backup of one project or all recently modified projects.
The backup will be downloaded to <BACKUP_FOLDER>/<project_id>. The filename of the backup is: <TASK_ID>.backup, where TASK_ID is the generated ID of the backup task.
The BACKUP_FOLDER is by default the current folder, but can be specified using the -f <path> command line argument.
The backup will be encrypted with a backup key. When not provided or prompted for, the backup key will be generated and written to a file in the key file folder.
The key file folder is by default the backup folder, but can be specified using the -kf <path> command line argument.
Example invocation to create a backup a project:
$ hansken backup -p deadbeef-c0de-c0de-c0de-badbadc0ffee
Example invocation to create a backup of all projects that are not backed up since their last modification (and have no running backup tasks):
$ hansken backup -m
hansken export
Command for initiating an export of the specified project -p <project_id>.
Exports can be optionally downloaded using flag -d/--download-export and configuring where to download the export to using option -f/--download-folder <path>,
if no download folder is explicitly provided the export will be downloaded to the current directory.
The export contains trace data from the specified project, filtered using a query -q/--query which defaults to * selecting everything.
What gets exported can further be finetuned using the following flags --export-priviliged, --export-notes, --export-tags, and --no-export-entities which all default to False.
The export will be encrypted using an export key that can be provided in multiple ways.
It can be provided using the -k/--user-export-key <export_key> option with export_key being a base64 encoded key.
Alternatively using the -K/--prompt-user-export-key flag the user will be prompted interactively to provided the base64 encoded export key.
Lastly, if the two above options are not used a key will be auto generated. In this case the generated key will be downloaded to --keys-folder <path>,
if one is not specified it will be downloaded to -f/--download-folder <path>, if neither is provided the key will be downloaded to the current directory.
Example invocation to export, and download that export, a project using a specified export key:
$ hansken export -p 4f893dee-f845-4c01-beb3-e71ccc2de11a -d -k 'PYA8jITrfBXnJgh5LuJR9znS44DBQNlm2B780nXO8yQ='
To export a portable case, use the flags --include-image-data combined with image-id <image-id>. Next to the trace data,
a new sliced image will be generated containing only the image data related to the exported traces.
hansken import
Command for initiating an import of a specified export file into a specified project -p <project_id>.
Imports are under the hood a two stage process, step one prepares the import, this includes uploading the export file.
Step one is the actual import/application of the export file to the specified project, this second step can be skipped using flag --no-apply-import.
Both the preparation stage and the apply stage are blocking till the respective tasks are completed.
For the apply stage it can be disabled using flag --no-wait-for-apply.
For the preparation stage it can be disabled using flag --no-wait-for-import, this flag gets ignored unless the apply stage is skipped using flag --no-apply-import.
The export file that is to be imported was encrypted during export.
During imports this file needs to be decrypted using the original export key, this key can be provided in multiple ways.
It can be provided using the -k/--user-export-key <export_key> option with export_key being a base64 encoded key.
Alternatively using the -K/--prompt-user-export-key flag the user will be prompted interactively to provided the base64 encoded export key.
The export file contains some metadata from the exported project and images, e.g. the description.
During import this metadata can be used to enrich the target project and images.
Using the --project-metadata-import-strategy ignore/update/update_and_overwrite and --image-metadata-import-strategy ignore/update/update_and_overwrite
flags this can be configured for project and image metadata respectively.
With the ignore import strategy the relevant metadata available in the export file gets ignored and is not used to update the target project/images.
Selecting update causes the import process to set any empty metadata fields in the target project/images to the value found in the export.
When selecting update_and_overwrite any metadata value in the export is used to overwrite the existing metadata of the target project/images.
Both the project and image metadata import strategies default to update.
Example invocation to import an export file (including applying the import) into a project using a specified export key:
$ hansken import /home/user/exports/5e600dd0-3f1b-43e7-be13-25c06bfc55de.export -p '554537c1-2082-466b-bb93-c0a08ed611ac' -k 'baXtqsKE8C+NosYgJ2b1b0Px33lY817VXP+yNwHGjO0='
Extending the command line for fun and profit
Users can control much of the command line behaviour of hansken.py through functions defined in the hansken.tool module.