Skip to content

Commit

Permalink
docs: improve readme
Browse files Browse the repository at this point in the history
  • Loading branch information
cugu committed Oct 14, 2024
1 parent 2fa04b9 commit 37ac523
Show file tree
Hide file tree
Showing 2 changed files with 45 additions and 17 deletions.
62 changes: 45 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,33 +4,61 @@
<a href="https://godocs.io/github.com/forensicanalysis/artifactcollector"><img src="https://godocs.io/github.com/forensicanalysis/artifactcollector?status.svg" alt="doc" /></a>
</p>

The artifactcollector project provides a software that collects forensic artifacts
on systems. These artifacts can be used in forensic investigations to understand
attacker behavior on compromised computers.
The artifactcollector is a tool to collect forensic artifacts on a system.
It can be used in forensic investigations to extract specific data instead of creating full disk images.
The artifactextractor can collect low-level (like $MFT)
and high-level file artifacts as well as registry keys (e.g. run keys)
which can then be used in forensic investigations.

![Running the artifactextractor on Windows.](docs/ac.png)
_Running the artifactextractor on Windows._

The artifactcollector is a single binary that can be transferred to computers
which are part of a forensic investigation.

## Features

The artifactcollector offers the following features

- ️🖥️ Runs on Windows, Linux and macOS
- Supports Windows 2000, Windows XP, and newer
- 🛍️ Can extract files, directories, registry entries, command and WMI output
- ⭐ Uses the configurable and extensible [Forensics Artifacts](https://github.com/forensicanalysis/artifacts)
- 🕊️ Open source
- ️🖥️ Runs on **Windows**, **Linux** and **macOS**
- 🏛️ Supports also old Windows versions like **Windows 2000** or **Windows XP**
- 🛍️ Can extract **files**, **directories**, **registry entries**, **command output**, and **WMI output**
- ⭐ Uses the configurable and extensible [**Forensics Artifacts**](https://github.com/forensicanalysis/artifacts)
- 🧩 Can run additional **embedded executables**
- 🕊️ **Open source**

## Download

All releases of the artifactcollector can be downloaded from [Releases](https://github.com/forensicanalysis/artifactcollector/releases).
Prebuild artifactcollectors for Windows, Linux and macOS are available.
Those artifactcollectors collect a predefined set of artifacts which are mostly taken from the Sans FOR500 training.
Sans provides a comprehensive [poster](https://www.sans.org/security-resources/posters/windows-forensic-analysis/170/download)
explaining those artifacts.

## Usage

### Installation
> [!WARNING]
> The artifactcollector behaves similar to malware as it collects critical system files
> and might be detected as a virus or malware.
Download the latest release for your operating system
from https://github.com/forensicanalysis/artifactcollector/releases
On Windows the `artifactcollector.exe` can be executed by double-clicking it on the investigated machine.
The user will be provided with a [UAC prompt](https://en.wikipedia.org/wiki/User_Account_Control) because the
artifactcollector required administrator rights to run.
The collection takes some minutes, depending on processing power and contained artifacts.

### Usage
On Linux and macOS the `artifactcollector` needs to be executed as root, e.g. `sudo artifactcollector`.
macOS can still prevent the execution, in this case right-click the artifactcollector,
select "Open", confirm "Open" and then try again with `sudo artifactcollector`.

On Windows, you can run the artifactcollector by double-clicking the executable.
You may need to confirm the UAC prompt.
## Output

On Linux and macOS, you can run the artifactcollector from the terminal: `./artifactcollector`.
The artifactcollecor will create a zip file and a log file.
The log file serves two purposes:
inform an investigator about errors during the collection but
also give the user a way to know what elements were extracted.
The zip file contains the results of the extraction and needs to be transferred back to the investigator.

### Build your own artifactcollector
## Build your own artifactcollector

1. Clone the repository: `git clone https://github.com/forensicanalysis/artifactcollector`.
2. Add artifact definition yaml files as needed in `config/artifacts`. Do not edit the
Expand All @@ -40,7 +68,7 @@ On Linux and macOS, you can run the artifactcollector from the terminal: `./arti
to enable the icon for the executable and the UAC popup.
5. Run `make build` to generate the artifactcollector binary.

### Embed binaries
## Embed binaries

Binaries can be added to `config/bin` and then included into the artifactcollector
in the `make build` step. Additionally, a corresponding COMMAND artifact like
Expand Down
Binary file added docs/ac.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 37ac523

Please sign in to comment.