If you want to submit evidence with your own automation, you can create a custom receptor or use the Evidence API
Option 1: Custom Receptor
Developers can create their own custom receptors with a user experience just like one of the Trustero-provided receptors in the platform.
More information: template project and the Receptor SDK in GitHub.
Option 2: Evidence API
This allows submitting evidence in a lighter weight way, for example via the command line. The level of effort is less than creating a custom receptor, but it doesn't provide the full receptor user experience.
Additional details in the below readme and addEvidence.sh files.
Readme.md
# How to use this script
This script will need to be run in a Bash environment.
This script will also require grpcurl to be installed on the system
## Install Instructions
### MacOS
1. Install brew
```sh
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
2. Install grpcurl
```sh
brew install grpcurl
```
### Linux
```sh
apt-get update -y
apt-get install wget -y
wget https://github.com/fullstorydev/grpcurl/releases/download/v1.1.0/grpcurl_1.1.0_linux_x86_64.tar.gz
tar -xvzf grpcurl_1.1.0_linux_x86_64.tar.gz
chmod +x grpcurl
mv grpcurl /usr/local/bin/grpcurl
```
### Windows
1. Install WSL
> You can now install everything you need to run Windows Subsystem for Linux (WSL) by entering this command in an administrator PowerShell or Windows Command Prompt and then restarting your machine.
```sh
wsl --install
```
2. Restart your machine
3. Install grpcurl
```sh
apt-get update -y
apt-get install wget -y
wget https://github.com/fullstorydev/grpcurl/releases/download/v1.1.0/grpcurl_1.1.0_linux_x86_64.tar.gz
tar -xvzf grpcurl_1.1.0_linux_x86_64.tar.gz
chmod +x grpcurl
mv grpcurl /usr/local/bin/grpcurl
```
4. Confirm that grpcurl in stalled
```sh
grpcurl --help
```
## Get your API token
You will need an api token to use this script. To copy your token, go to:
https://app.trustero.com/
Click on the circle on the top right of the page that represents your account. This will pop open a menu displaying your email and avatar.
To get the api token, you will need to click on your email address on the page.
The API token will be copied to your clipboard/paste buffer.
You will need this token when running the script to post evidence into your account.
## Using the script
The script has 2 functions
1. Get a list of all in-scope controls from your account
- you will need to add the -g flag, and the -t flag with your token
```sh
./addEvidence.sh -t {your-token} -g
```
2. Post a piece of evidence to a specific control
- this will require the a caption, control, evidence, and token to successfully add evidence
- you will need to add the -t flag with your token
- the -a flag will set the caption
- the -c flag will specify the control that this evidence will be posted to
```
NOTE: For the -c flag, you will need to use the control's unique ID. You can find this by using the list controls command mentioned above.
```
- the -e flag will specify the evidence. This can be a string/markdown, or it can be a path to a file
- if submitting string text or markdown as evidence, you will need to set the mime type
- this is done by setting the -m flag to `text/markdown` example below:
```sh
./addEvidence.sh -t {your-token} -a "This is a caption" -c "trc1" -e "This is detailed text in the body of the evidence" -m "text/markdown"
```
This is an example of submitting a pdf:
```sh
./addEvidence.sh -t {your-token} -a "A list of all users" -c "trc1" -e ./users.pdf
```
addEvidence.sh
#! /bin/bash
set -e
function help() {
# Display Help
echo "This script requires a bash environment."
echo "If on windows, you will need to install Windows Subsystem for Linux:"
echo "https://docs.microsoft.com/en-us/windows/wsl/install"
echo
echo "You will also need to install brew:"
echo "On Windows: https://docs.brew.sh/Homebrew-on-Linux"
echo "On Mac: https://brew.sh/"
echo
echo "Finally, you will need to install grpcurl via brew: "
echo "https://github.com/fullstorydev/grpcurl#homebrew-macos"
echo
echo "options:"
echo "-a [REQUIRED] Set the caption for your evidence"
echo "-e [REQUIRED] Path to evidence file or inline string/text/markdown"
echo "-c [REQUIRED] The control the evidence will be posted to ex: trc64"
echo "-g This flag will determine what API call is being made. If set,"
echo " the scirpt will retrieve a list of in-scope controls from your account"
echo "-h Display the help menu"
echo "-m Set the mime type for your evidence. If sending text or markdown,"
echo " this will need to be set to $()$(text/markdown)$()"
echo "-t [REQUIRED] API token for the Trustero Account"
}
while getopts 'a:e:c:ghm:t:' arg; do
case $arg in
a) caption=${OPTARG} ;;
e) evidence=${OPTARG} ;;
c) control=${OPTARG} ;;
g) ;;
h) # Display help.
help
exit
;;
m) mime=${OPTARG} ;;
t) token=${OPTARG} ;;
esac
done
function msg() {
echo $@ 1>&2
}
if ! command -v grpcurl &> /dev/null; then
msg "grpcurl could not be found, please install grpcurl via brew"
exit 1
fi
function getAllControls() {
msg "starting getAllControls"
grpcurl -H "Authorization: Bearer $token" -d '' prod.api.infra.trustero.com:8443 model.Model/ListControls
}
function addEvidenceToControl() {
msg "starting addEvidenceToControl"
if [[ -z $evidence ]]; then
msg "no evidence provided!"
exit
fi
if [[ -z $control ]]; then
msg "no control specified!"
exit
fi
if [[ -z $caption ]]; then
msg "no caption for evidence!"
exit
fi
if [ "$mime" == "text/markdown" ]; then
base64Data=$(echo $evidence | base64)
else
mime=$(file -b --mime-type "$evidence")
base64Data=$(base64 "$evidence")
fi
data="{\"document\":{"
data+="\"SubjectModelType\":\"2\","
data+="\"ActorType\":\"0\","
data+="\"DocType\":\"2\","
data+="\"Mime\":\"$mime\","
data+="\"Body\":\"$base64Data\","
data+="\"Caption\":\"$caption\","
data+="\"SubjectID\":\"$control\""
data+="}}"
# To the grpc call, we add the AddDocumentRequest message
grpcurl -H "Authorization: Bearer $token" -d "$data" prod.api.infra.trustero.com:8443 attachment.Attachment/AddDocument
}
if [[ -z $token ]]; then
msg "no token!"
exit 1
elif [[ $* == *" -g "* ]]; then
getAllControls
else
addEvidenceToControl
fi
msg Done