Skip to content

Incident Response Report Using GitHub-Sphinx

License

Notifications You must be signed in to change notification settings

guardsight/gsvsoc_mission-model

Repository files navigation

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.

img

img

Prerequisites

  1. Familiarity with contributing to Github

  2. Authorized access to Github

  3. Familiarity with publishing documentation using Sphinx

  4. Sphinx software for Local builds (optional but recommended)

    pip install sphinx sphinx-autobuild
  5. 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
  6. Github Settings

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

Instruction

img

Bootstrap
  1. 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':
  2. Duplicate a template repo without forking it and mirror-push its contents into the new repo
    git clone --bare [email protected]:guardsight/gsvsoc_mission-model MISSION-BOOTSTRAP
    cd MISSION-BOOTSTRAP/
    git push --mirror [email protected]:${MYORG}/${MISSION}
    cd .. && rm -rf MISSION-BOOTSTRAP
  3. Create a development branch and incorporate the remote repo into the local branch
    git clone [email protected]:${MYORG}/${MISSION} ${MISSION}
    cd ${MISSION}
    git checkout develop
    git pull origin develop
    cd docs
  4. Replace some default content
    sed -i "s/MISSION-YYYYMMDD-n/${MISSION}/g" source/index.rst source/meta.txt source/conf.py
  5. Replace the GuardSight copyright with ${MYORG} copyright
  6. 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
  1. 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
  2. Merge into Master -> Push
    git checkout master
    git merge develop
    git push --tags origin master
    git checkout develop
    
Local Build
  1. Make up the build
    cd ${MISSION}/docs
    make singlehtml
    make latexpdf
    
  2. View the document
    google-chrome build/singlehtml/index.html
    google-chrome build/latex/gsvsoc_mission-model.pdf
    
Read the Docs For Business Build (optional)
  1. Import the repo into RTD
    google-chrome https://readthedocs.com/dashboard/import/?
    
  2. View the document
    google-chrome https://${MYORG}-$(echo ${MISSION} | tr [[:upper:]] [[:lower:]]).readthedocs-hosted.com/en/latest/