Dexter
Your friendly forensics expert.
Dexter is a forensics acquisition framework designed to be extensible and secure.
Dexter runs as an agent backed by S3. Investigators use Dexter on the command line to issue investigations and retrieve reports. Investigations define facts that must be true about the systems in scope, and tasks that will be ran on the host. After tasks are ran, Dexter generates reports that are individually encrypted back to the investigators that are authorized to view the data.
Architecture Overview
Building
Prerequisites
A working go environment
You must have go installed. Please follow the installation instructions or use a alternative method such that you can successfully run go and have a properly setup $GOPATH defined in your environment.
Dexter uses Go modules, so you must export GO111MODULE=on in your environment.
Download the repository
Clone the repository into the correct place in your $GOPATH.
cd $GOPATH/src
mkdir -p github.com/coinbase
cd github.com/coinbase
git clone github.com/coinbase/dexter
cd dexter
Run tests
make test
Install
Dexter can be installed with:
make install
On linux, a bash completion script can be installed with make bash.
Dexter will need to be configured before it can be used.
Environment variables
Dexter is configured with the following environment variables. Some are only required when Dexter is running as a daemon, others are required both when acting as a daemon as well as a command line client.
| Envar | Use | Daemon | Client |
|---|---|---|---|
DEXTER_AWS_S3_BUCKET |
The S3 bucket Dexter will use | β | β |
DEXTER_POLL_INTERVAL_SECONDS |
The number of seconds in between Dexter S3 polls | β | |
DEXTER_PROJECT_NAME_CONFIG |
Instructs Dexter on how to look up a local host's project name. Contents must being with file://, followed by a local path, or envar://, followed by an envar name. |
β | |
DEXTER_OSQUERY_SOCKET |
Path to the local osquery socket | β | |
DEXTER_AWS_ACCESS_KEY_ID |
AWS access key, used to override AWS_ACCESS_KEY_ID. If not set, AWS_ACCESS_KEY_ID will be used instead. |
β | β |
DEXTER_AWS_SECRET_ACCESS_KEY |
AWS access key, used to override AWS_SECRET_ACCESS_KEY. If not set, AWS_SECRET_ACCESS_KEY will be used instead. |
β | β |
DEXTER_AWS_REGION |
AWS access key, used to override AWS_REGION. If not set, AWS_REGION will be used instead. |
β | β |
Amazon S3 access
In order to use Dexter, you will need to have access to an S3 bucket.
Dexter usage can be divided into three roles: daemon, investigator, and admin.
Daemon
Dexter daemons will need to the following aws permissions to use the S3 bucket:
ListBucketoninvestigationsListBucketoninvestigations/*ListBucketoninvestigatorsListBucketoninvestigators/*GetObjectoninvestigationsGetObjectoninvestigations/*GetObjectoninvestigatorsGetObjectoninvestigators/*PutObjectonreports/*PutObjectAclonreports/*
Investigators
Investigators will require the following permissions to use Dexter:
GetObjecton the entire bucketListBucketon the entire bucketPutObjectoninvestigations/*PutObjectAcloninvestigations/*
Admins
Dexter admins should have all the permissions of investigators, as well as the following additional permissions:
PutObjecton the entire bucketPutObjectAclon the entire bucketCopyObjecton the entire bucketDeleteObjecton the entire bucket
Only Dexter admins can add new users and archive reports.
Usage
Full documentation for dexter is auto-generated here.
Setting up an investigator
The command dexter investigator init can be used to create a new investigator on a new system. You will set a new password which will be used when investigations are signed and reports are downloaded.
$ ./dexter investigator init hayden
Initializing new investigator "hayden" on local system...
Set a new password >
Confirm >
New investigator file created: hayden.json
This must be uploaded to Dexter by your Dexter administrator.
A dexter admin can now place this file in the investigators directory of the S3 bucket.
This will create a ~/.dexter directory locally containing your encrypted private key.
Revoking investigators
The command dexter investigator emergency-revoke can be used to revoke an investigator.
Deploying the daemon
The command dexter daemon is used to start a daemon.
Dexter daemon can be deployed either as a binary or as a docker container. When deployed via docker, it is important to provide Dexter with access to the docker socket and osquery socket, if you intend on using those features. The Dockerfile included in this repo is a good place to start, but will require the configuration file to be edited before building.
Creating an investigation
The command dexter investigation create is used to create new investigations.
Running this command will enter into an interactive cli where an investigation can be configured, signed, and uploaded.
Listing investigations
The command dexter investigation list is used to list all investigations stored in the Dexter bucket.
$ dexter investigation list
+---------------+--------+-------------------------+------------------------+-----------+-------------+
| INVESTIGATION | ISSUER | TASKS | SCOPE | CONSENSUS | REVIEWED BY |
+---------------+--------+-------------------------+------------------------+-----------+-------------+
| 1e8b73bb | bob | docker-filesystem-diff, | platform-is("linux"), | 1/1 | alice |
| | | osquery-collect | user-exists(REDACTED) | | |
+---------------+--------+-------------------------+------------------------+-----------+-------------+
Approving investigations
The command dexter investigation approve is used to preview and sign investigations that require consensus approval.
$ dexter investigation approve 1
Provide your password to approve the following investigation:
+------------------+--------------------------------+
| FIELD | VALUE |
+------------------+--------------------------------+
| ID | 1e8b73bb |
| Issued By | bob |
| Tasks | osquery-collect, |
| | docker-filesystem-diff |
| Scope | platform-is("linux"), |
| | user-exists(REDACTED) |
| Kill Containers? | false |
| Kill Host? | false |
| Recipients | alice, bob |
| Approvers | |
+------------------+--------------------------------+
Password >
Archiving investigations
The command dexter investigation archive is used to rename old investigations so they are no longer visible.
When this command is ran, all past investigations will be prefixed with an underscore and no longer visible in Dexter. They are still available in the S3 bucket for audit purposes.
Listing reports
The command dexter report list is used to print a table of reports.
$ dexter report list
+---------------+--------+-------------------------+-----------------------+------------+----------------+
| INVESTIGATION | ISSUER | TASKS | SCOPE | RECIPIENTS | HOSTS UPLOADED |
+---------------+--------+-------------------------+-----------------------+------------+----------------+
| 1e8b73bb | bob | docker-filesystem-diff, | platform-is("linux"), | alice, | 1 |
| | | osquery-collect | user-exists(REDACTED) | bob | |
+---------------+--------+-------------------------+-----------------------+------------+----------------+
Downloading reports
The command dexter report retrieve is used to download reports.
The encrypted report will be downloaded, and you will be prompted for your password. Once provided, the report will be populated in a new directory.
The report format is:
DexterReport-<ID>/<hostname>/<taskname>/...
Archiving reports
The command dexter report archive is used to archive old reports.
The reports will be prefixed with an underscore and no longer visible in Dexter. They will remain in the S3 bucket for audit purposes.
Development
Adding facts
New facts can be added very easily. Make a copy of the example fact and replace the contents as needed with your new fact. Rebuild and re-deploy dexter, and your fact will be available for use.
Adding tasks
New tasks can be added just like new facts. Make a copy of the example task, replacing the content as needed, and redeploy.