Skip to content

Developer

Jump to bottom
John Kennedy edited this page Mar 16, 2021 · 4 revisions

🛠️ 1. Building

Build steps below for Mac are derived from our ci.yaml file, which should be viewed for full details.

Install QT5

brew install qt@5
export PATH="/usr/local/opt/qt/bin:$PATH"
brew link -f qt

Clone Repository

git clone --recurse-submodules https://github.com/theparanoids/ashirt.git

Build the App

qmake -config release
make -j4
macdeployqt ashirt.app -dmg

Bundle License and Readme

mkdir dist
cp ashirt.dmg dist/ashirt.dmg
cp LICENSE dist/LICENSE
cp README.md dist/README.md
zip -r ashirt.zip dist/

2. Build Requirements

This application is built off of Qt 5, and utilizes's Qt's networking and Sql featuresets. To build, your specific system may need the following:

  1. Qt 5, qmake, and possibly Qt Creator IDE.
    1. Binaries located here. You may need to alter which downloader you install.
  2. SQLite C driver (for SQLite version 3)
    1. On Fedora, this can be installed with yum install sqlite-devel
    2. On Arch systems, this can be installed with pacman -S sqlite-doc

Versioning and Update Checks

This application has the ability to check for updates, and present a notification to the user that an update exists. In order to do this, the application needs to know a few key pieces of data. First, the application needs to know what version it is currently running. Second, it needs to know where to ask for new versions. Currently, the version check is accomplished by asking Github -- where this project is stored -- if there are any releases, and then manually checking those results against its stored version. The Adding Versioning section below details how these values are populated. Note, however, that for any user that wishes to fork this project, these sections will need to be modified in order to either point to your own service or repository, or disabled altogether.

This code is found by tracing its usage from it's initial request. Currently, this request started in NetMan::checkForNewRelease.

Adding Versioning

This application attempts to add versioning data when building. This is accomplished by leveraging qmake's ability to add in preprocessor macros. This can be seen by looking in the ashirt.pro file, specifically looking for the DEFINES definition/updates, and tracing those additions back. For this project in particular a few fields are defined:

Field default Value Meaning
VERSION_TAG v0.0.0-development Contains the release tag, if any. Expects a Semantic Version. Displayed to the user, and used for update checks.
COMMIT_HASH Unknown Contains the commit hash used when building this release. Displayed to the user
SOURCE_CONTROL_REPO (empty string) Contains the path to source control, relative to source control's domain. As this relates to github, this should be of the form owner/repo, or, for this project theparanoids/ashirt

Currently, these fields are populated by looking at environment variables that GitHub Actions provides. If forking, these environment variables can be replaced by looking for $$getenv(GITHUB_ prefixes in the ashirt.pro file

Adding a db migration

Updating the database schema is slightly complicated, and the following rules must be followed:

  1. Use the helper script bin/create-migration.sh
    • This will create file in the migrations folder with the indicated name and a timestamp
    • This should also add this migration to the qrc file. However, if this is not done, you can do this manually by editing the rs_migrations.qrc file.
  2. Inside the new migration file, add the necessary sql to apply the db change under -- +migrate Up
  3. Inside the new migration file, add the necessary sql to undo the db change under -- +migrate Down
  4. Only one statement is allowed under each heading. If multiple statements need to be applied, they should done as multiple migration files
    • This is a sqlite3/Qt limitation.

Adding a new Evidence Filter

Evidence filters require modification in a few files and functions. Here is a rough checklist:

File Function Notes
evidencefilter.h Need to add FILTER_KEY_ and FILTER_KEYS_ values
evidencefilter.cpp standardizeFilterKey Needed to map filter key alias to the one true filter key
evidencefilter.cpp toString Need to represent a filter key/value as a string
evidencefilter.cpp parseFilter Need to be able to read filter key/value from a string
databaseconnection.cpp getEvidenceWithFilters Need to translate the filter key/value to an appropriate sql clause

Currently, there is already built-in support for adding filters of type:

  • String (use the Operation filter as a guide)
  • Boolean/Tri (Tris represent Yes/No/Any here, use Error filter as a guide)
  • Date Range (use To/From filters as a guide)

Formatting

This application adopts a modified Google code style, applied via clang-format. Note that while formatting style is adhered to, other parts may not be followed, due to not starting with this style in mind.

Google style changes:

  • Line limit to 100 characters
    • This is simply easier to read when dealing with long lines
  • Line breaks before else and catch.
    • This is mostly because I find these easier to read.

To apply code formatting (Linux/Bash), run find src/ -iname "*.cpp" -o -iname "*.h" | xargs clang-format -i

Known Issues

  1. Evidence manager columns aren't ideally sized
  2. No CLI for non-qt/non-tray OSes
  3. Remove dock icon on mac?
    1. Possibly useful: https://github.com/keepassxreboot/keepassxc/commit/45344bb2acea61806d5e7f5f9eadfa779ca536ae#diff-a9e708931297992b08350ff7122fcb91R157

Recommendations for tasks

  1. Imports are not versioned or identifiable.
    1. Identification can be accomplished by adding a uuid to the system.json export, and having a table that keeps track of which imported uuids have been used
    2. Simple, perhaps ineffectual, versioning could be accomplished by using the ID above, and adding a column to the evidence table, indicating which export batch was associated with that evidence. The export evidence.json would then need to add this identification to each entry where this value was known.
    3. An alternative for identification could be to hash (e.g. md5) each file and provide that has in evidence.json. A similar hash would need to exist on each piece of evidence in the database. The system could then use that hash, in combination with other data, to determine if this evidence has been previously imported.
    4. A third alternative would be to go by the server's evidenceID or slug, if available (this is currently not tracked locally). A separate mechanism would be needed for non-submitted evidence.
Clone this wiki locally