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.
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.
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
make test
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.
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. |
✓ | ✓ |
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.
Dexter daemons will need to the following aws permissions to use the S3 bucket:
ListBucketoninvestigationsListBucketoninvestigations/*ListBucketoninvestigatorsListBucketoninvestigators/*GetObjectoninvestigationsGetObjectoninvestigations/*GetObjectoninvestigatorsGetObjectoninvestigators/*PutObjectonreports/*PutObjectAclonreports/*
Investigators will require the following permissions to use Dexter:
GetObjecton the entire bucketListBucketon the entire bucketPutObjectoninvestigations/*PutObjectAcloninvestigations/*
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.
Full documentation for dexter is auto-generated here.
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.
The command dexter investigator emergency-revoke can be used to revoke an investigator.
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.
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.
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) | | |
+---------------+--------+-------------------------+------------------------+-----------+-------------+
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 >
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.
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 | |
+---------------+--------+-------------------------+-----------------------+------------+----------------+
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>/...
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.
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.
New tasks can be added just like new facts. Make a copy of the example task, replacing the content as needed, and redeploy.