Awesome

How-To Develop An Incident Response Report Journal Using GitHub, Sphinx, RTD

Documenting Incident Response Using GitHub, Sphinx, RTD

Prologue

GuardSight analysts use a systematic approach to achieve the objectives of containment, eradication, and recovery during its BreachMasters™ incident response. One component of this approach includes developing content iteratively, in the style of journaling, to describe the adversary compromise as well as the allied response. The aggregated journal content ultimately results in an after action report. Producing the report documentation while conducting the response activities has many benefits including memorializing in near real-time, the increased accuracy of observations and collections, and improved precision of knowledge transfers when transitioning between analysts to manage response fatigue. This document discusses a mechanism for developing the incident response content using the revision control hosting system Github, use of the Sphinx documentation generator, and the optional use of the software hosting system Read the Docs.

Prerequisites

Familiarity with contributing to Github
Authorized access to Github
Familiarity with publishing documentation using Sphinx
Sphinx software for Local builds (optional but recommended)
```
pip install sphinx sphinx-autobuild
```
Authorized access to Read the Docs for business private hosting (optional)
- Non-redacted public postings of after action reports is probably not smart - readthedocs.com is private - readthedocs.io is public

Github Settings

vi ~/.gitconfig
[user]
    name = myName
    email = myName@myEmailDomain

Instruction

Bootstrap

Create a new repo that will contain the after action report (notice the private key has its boolean value set to true)

cd ~/sandbox/code/github
MISSION=$(date +'MISSION-%Y%m%d-1')
MYORG=guardsight # e.g. ==> https://github.com/${MYORG} <== assign MYORG=yourOrganization
curl -u $(grep name ~/.gitconfig | awk '{print $NF}') -d '{ "name": "'${MISSION}'", "description": "Incident Response Journal", "private": true, "has_wiki": false }' https://api.github.com/orgs/${MYORG}/repos
Enter host password for user 'myName':

Duplicate a template repo without forking it and mirror-push its contents into the new repo

git clone --bare git@github.com:guardsight/gsvsoc_mission-model MISSION-BOOTSTRAP
cd MISSION-BOOTSTRAP/
git push --mirror git@github.com:${MYORG}/${MISSION}
cd .. && rm -rf MISSION-BOOTSTRAP

Create a development branch and incorporate the remote repo into the local branch

git clone git@github.com:${MYORG}/${MISSION} ${MISSION}
cd ${MISSION}
git checkout develop
git pull origin develop
cd docs

Replace some default content

sed -i "s/MISSION-YYYYMMDD-n/${MISSION}/g" source/index.rst source/meta.txt source/conf.py

Replace the GuardSight copyright with ${MYORG} copyright
Replace docs/source/meta-logo.png with ${MYORG} logo

IT IS PERMISSABLE TO REPLACE THE LOGO AND COPYRIGHT NOTICE IN THE CLONED ${MISSION} AND THE GUARDSIGHT PERMISSION NOTICE IS NOT REQUIRED TO BE INCLUDED IN THE CLONED ${MISSION} OR ANY PORTION OF THE AFTER ACTION REPORT

Edit <=> Commit

Develop -> Commit -> Push

cd ${MISSION}
git checkout develop; git pull origin develop; cd docs
gedit source/*.rst source/meta.txt # sudo apt install gedit-plugin-git; # this shows lines that have changed since last commit;
# make some changes
git commit -a -m "Mission update"
git push --tags origin develop

Merge into Master -> Push

git checkout master
git merge develop
git push --tags origin master
git checkout develop

Local Build

Make up the build

cd ${MISSION}/docs
make singlehtml
make latexpdf

View the document

google-chrome build/singlehtml/index.html
google-chrome build/latex/gsvsoc_mission-model.pdf

Read the Docs For Business Build (optional)

Import the repo into RTD

google-chrome https://readthedocs.com/dashboard/import/?

View the document

google-chrome https://${MYORG}-$(echo ${MISSION} | tr [[:upper:]] [[:lower:]]).readthedocs-hosted.com/en/latest/