Beagle - An Incident Reply In Addition To Digital Forensics Tool Which Transforms Safety Logs In Addition To Information Into Graphs

Beagle is an incident response in addition to digital forensics tool which transforms information sources in addition to logs into graphs. Supported information sources include FireEye HX Triages, Windows EVTX files, SysMon logs in addition to Raw Windows retention images. The resulting Graphs tin john endure sent to graph databases such equally Neo4J or DGraph, or they tin john endure kept locally equally Python NetworkX objects.

Beagle tin john endure used straight equally a python library, or through a provided spider web interface.

The library tin john endure used either equally a sequence of functional calls.

>>> from beagle.datasources import SysmonEVTX  >>> graph = SysmonEVTX("malicious.evtx").to_graph() >>> graph 

Or past times strictly calling each intermediate pace of the information source to graph process.

>>> from beagle.backends import NetworkX >>> from beagle.datasources import SysmonEVTX >>> from beagle.transformers import SysmonTransformer  >>> datasource = SysmonEVTX("malicious.evtx")  # Transformers accept a datasource, in addition to transform each trial # into a tuple of 1 or to a greater extent than nodes. >>> transformer = SysmonTransformer(datasource=datasource) >>> nodes = transformer.run()  # Transformers output an array of nodes. [     ( process_guid="{0ad3e319-0c16-59c8-0000-0010d47d0000}"),     ( host="DESKTOP-2C3IQHO" full_path="C:\Windows\System32\services.exe"),     ... ]  # Backends accept the nodes, in addition to transform them into graphs >>> backend = NetworkX(nodes=nodes) >>> G = backend.graph() 

Graphs are centered exactly about the activity of private processes, in addition to are meant primarily to assistance analysts investigate activity on hosts, non betwixt them.

Installation

Docker
Beagle is available equally a docker file:

docker trace yampelo/beagle mkdir -p data/beagle docker run -v "$PWD/data/beagle":"/data/beagle" -p 8000:8000 yampelo/beagle

Python Package
It is also available equally library. Full API Documentation is available on https://beagle-graphs.readthedocs.io

pip install pybeagle

Configuration

• Complete overview of each configuration entry

Any entry inwards the configuration file tin john endure modified using environs variables that follow the next format; BEAGLE__{SECTION}__{KEY}. For example, inwards social club to alter the VirusTotal API Key used when using the docker image, y'all would exercise -e parameter in addition to laid upwards the BEAGLE__VIRUSTOTAL__API_KEY variable:

docker run -v "data/beagle":"/data/beagle" -p 8000:8000 -e "BEAGLE__VIRUSTOTAL__API_KEY=$API_KEY" beagle

Environment variables in addition to directories tin john endure easily defined using docker compose

version: "3"    services:      beagle:          image: yampelo/beagle          volumes:              - /data/beagle:/data/beagle          ports:              - "8000:8000"          environment:              - BEAGLE__VIRUSTOTAL__API_KEY=$key$  

Web Interface
Beagle's docker icon comes amongst a spider web interface that wraps exactly about the procedure of both transforming information into graphs, equally good equally using them to investigate data.

Uploading Data

The upload cast wraps exactly about the graph creation process, in addition to automatically uses NetworkX equally the backend. Depending on the parameters required past times the information source, the cast volition either prompt for a file upload, or text input. For example:

• VT API Sandbox Report asks for the hash to graph.
• FireEye HX requires the HX triage.

Any graph created is stored locally inwards the folder defined nether the dir fundamental from the storage department inwards the configuration. This tin john endure modified past times setting the BEAGLE__STORAGE__DIR enviroment variable.
Optionally, a comment tin john endure added to whatsoever graph to amend assistance depict it.
Each information source volition automatically extract metadata from the provided parameter. The metadata in addition to comment are visible afterwards on when viewing the existing graphs of the datasource.

Browsing Existing Graphs
Clicking on a datasource on the sidebar renders a tabular array of all parsed graphs for that datasource.

Graph Interface
Viewing a graph inwards Beagle provides a spider web interface that allows analysts to speedily pin exactly about an incident.
The interface is split into 2 master copy parts, the left component subdivision which contains diverse perspectives of the graph (Graph, Tree, Table, etc), in addition to the correct component subdivision which allows y'all to filter nodes in addition to edges past times type, search for nodes, in addition to expand a nodes properties. It also allows y'all to undo in addition to redo operations y'all perform on the graph.
Any chemical factor inwards the graph that has a divider inwards a higher house it is collapsible:

Inspecting Nodes in addition to Edges
Nodes inwards the graph display the offset xv characters of their a specific field. For example, for a procedure node, this volition endure the procedure name.
Edges merely present the border type.
Influenza A virus subtype H5N1 single click on a node or border volition focus that node in addition to display its information inwards the "Node Info" panel on the correct sidebar.

Focusing on a Node

Focusing on an Edge

Expanding Neighbours
Influenza A virus subtype H5N1 double click on a node volition trace inwards whatsoever neighbouring nodes. Influenza A virus subtype H5N1 neighbouring node is whatsoever node connected to the clicked on node past times an edge. If at that topographic point are no neighbors to endure pulled in, no alter volition endure seen inwards the graph.

• This is regardless of direction. That way that a bring upwards procedure or a minor fry procedure could endure pulled inwards when double clicking on a node.
• Beagle volition alone trace inwards 25 nodes at a time.

Hiding Nodes
Influenza A virus subtype H5N1 long unmarried click on a node volition shroud it from the graph, equally good equally whatsoever edges that depend on it.

Running Mutators
Right clicking on a node exposes a context card that allows y'all to run graph mutators. Mutators are functions which accept the graph state, in addition to homecoming a novel state.
Two extremely useful mutators are:

1. Backtracking a node: Find the sequence of nodes in addition to edges that led to the creation of this node.
   • Backtracking a procedure node volition present its procedure tree.
2. Expanding all descendants: From the electrical flow node, present every node that has this node equally an ancestor.
   • Expanding a procedure node volition present every minor fry procedure node it spawned, whatsoever file it may receive got touched, in addition to pretty much every activity that happened equally a consequence of this node.

Backtracking a node
Backtracking a node is extremely useful, in addition to is like to doing a root drive infection inwards log files.

Expanding Node Descendants
Expanding a node's descendants allows y'all to right away stance everything that happened because of this node. This activeness reveals the subgraph rooted at the selected node.

Toggling Node in addition to Edge Types
Sometimes, a Node or Edge powerfulness non endure relevant to the electrical flow incident, y'all tin john toggle border in addition to node types on in addition to off. As presently equally the type is toggled, the nodes or edges of that type are removed from the visible graph.
Toggling a node type off prevents that node type to endure used when using mutators, or when pulling inwards neighbours.

Undo/Redo Action in addition to Reset
Any activeness inwards the graph is right away reversable! Using the undo/redo buttons y'all tin john revert whatsoever activeness y'all perform. The reset push clit sets the graph Blue Planet to when it loaded, saving y'all a refresh.

Graph Perspectives
As y'all alter the graphs electrical flow Blue Planet using the inwards a higher house action, y'all powerfulness also want to stance the electrical flow laid upwards of visible node in addition to edges inwards a unlike perspective. The tabs at the top of the graph covert allow y'all to transform the information into a diverseness of views:

• Graph (Default perspective)
• Tree
• Table
• Timeline
• Markdown

Each of the perspectives supports focusing on nodes past times clicking on them.

Python Library
The graph generation procedure tin john endure performed programatically using the python library. The graph generation procedure is made upwards of 3 steps:

1. DataSource classes parse in addition to yield events 1 past times one.
2. Transformer classes accept those inputs, in addition to transform them into diverse Node classes such equally Process.
3. Backend classes accept the array of nodes, house them into a graph structure, in addition to post them to a desired location.

The Python bundle tin john endure installed via pip:

version: "3"  services:     beagle:         image: yampelo/beagle         volumes:             - /data/beagle:/data/beagle         ports:             - "8000:8000"         environment:             - BEAGLE__VIRUSTOTAL__API_KEY=$key$

Creating a graph requires chaining these together. This tin john endure done for y'all using the to_graph() function.

pip install pybeagle

It tin john also endure done explicitly at each step. Using the functional calls, y'all tin john also define which Backend y'all want to exercise for example, to post information to DGraph

from beagle.datasources import HXTriage  # By default, using the to_graph() degree uses NetworkX in addition to the offset transformer. G = HXTriage('test.mans').to_graph() 

When calling the to_graph or to_transformer methods, y'all tin john transcend inwards whatsoever arguments to those classes:

from beagle.datasources import HXTriage from beagle.backends import DGraph from beagle.transformers import FireEyeHXTransformer  # The information volition endure sent to the DGraph instance configured inwards the # configuration file backend = HXTriage('test.mans').to_graph(backend=DGraph)  # Can also specify the transformer backend = HXTriage('test.mans').to_transformer(transformer=FireEyeHXTransformer).to_graph(backend=DGraph)

You tin john also manually invoke each pace inwards the inwards a higher house process, accessing the intermediary outputs

from beagle.datasources import HXTriage from beagle.backends import Graphistry  # Send the graphistry, anonymize the information first, in addition to homecoming the URL graphistry_url = HXTriage('test.mans').to_graph(backend=Graphistry, anonymize=True, render=False)

If y'all want to manually telephone phone each step, y'all volition demand to ensure that the Transformer degree instance is compatible amongst the output of the provided DataSource class.

• All Backends are compatible amongst all Transformers.

Each information source defines the listing of transformers it is compatible with, in addition to this tin john endure accessed via the .transformers attribute:

>>> from beagle.backends import NetworkX >>> from beagle.datasources import HXTriage >>> from beagle.transformers import FireEyeHXTransformer  >>> datasource = HXTriage("test.mans") >>> transformer = FireEyeHXTransformer(datasource=datasource) >>> nodes = transformer.run() >>> backend = NetworkX(nodes=nodes) >>> G = backend.graph()

Controlling Edge Generation
By default, edges are non condensed, that way that if a procedure node u writes to a file node v 5000 times, y'all volition receive got 5000 edges betwixt those nodes. Sometimes, particularly when trying to visualize the data, this may overwhelm an analyst.
You tin john condense all 5000 edges into a unmarried border for that type of activeness (wrote inwards this case), past times passing the backend degree the consolidate_edges=True parameter, for example:

>>> from beagle.datasources import HXTriage >>> HXTriage.transformers [beagle.transformers.fireeye_hx_transformer.FireEyeHXTransformer]

By default, the spider web interface volition consolidate the edges.

Documentation

• REST API Overview
• Configuration
• Developement
• Design Logic

Download Beagle