This guide explains how to use the Unix Artifact Collector (UAC) to gather incident response artifacts from Unix-like systems, apply collection profiles, and manage output. You will learn to install UAC, run collections with tailored profiles, and interpret the resulting JSON or CSV output for forensic analysis.
What You’ll Need
- A Unix-like system (Linux, macOS, BSD) with root or sudo access for full artifact collection.
- Python 3.6 or later installed (UAC is Python-based).
- Internet access to download UAC, or a local copy of the repository.
- Basic familiarity with the command line and file permissions.
Step-by-Step
- Download UAC: Clone the official repository or download the latest release tarball from the project’s GitHub page. For example:
git clone https://github.com/tclahr/uac.gitand navigate into the directory. - Install dependencies: UAC requires Python packages like
psutilandtermcolor. Install them via pip:pip3 install -r requirements.txt. If you are on a system without internet, copy the dependencies manually. - Verify installation: Run
python3 uac.py --helpto confirm UAC is working. This shows available options and profile names. - Understand profiles: UAC comes with predefined profiles (e.g.,
linux,macos,freebsd) that define which artifacts to collect. Each profile is a YAML file in theprofilesdirectory. You can create custom profiles by copying and editing an existing one. - Run a basic collection: Execute
sudo python3 uac.py -p linuxto collect artifacts using the Linux profile. This creates a timestamped output directory undercollections(or a custom path if specified). - Specify output format: Use the
-foption to choose output format:json,csv, orhtml. For example:sudo python3 uac.py -p linux -f jsonproduces JSON files for each artifact. - Limit collection scope: To collect only specific artifacts, use the
-aoption with artifact names (comma-separated). For instance:sudo python3 uac.py -p linux -a users,groups,network. - Include extra artifacts: Use
-eto add extra artifact groups not in the profile, e.g.,-e processes,listening_ports. - Collect from a live system vs. image: For a live system, run as root. For a mounted image, use the
-moption to specify the mount point, and UAC will collect artifacts from there without altering the original. - Output location: By default, output is stored in
./collections/<hostname>-<timestamp>/. You can change this with-o /path/to/dir. - Review the output: After collection, navigate to the output directory. Each artifact is saved as a separate file (e.g.,
users.json,network.json). Open them to review the collected data. - Generate a report: UAC can generate an HTML report with
-f html. This creates an index.html that summarizes the collection and links to each artifact file.
Common Mistakes
- Running without sudo: Many artifacts (like process memory, logs, or /etc/shadow) require root privileges. Without sudo, collection fails or returns incomplete data.
- Using the wrong profile for the OS: For example, using the
linuxprofile on macOS will skip macOS-specific artifacts and may error on paths. Always select the matching profile. - Ignoring output format: The default is text, which is hard to parse. Use
-f jsonfor structured output that can be ingested by SIEM or analysis tools. - Not checking disk space: Large collections (especially with memory or full filesystem listings) can consume gigabytes. Ensure enough free space in the output directory.
- Overwriting previous collections: If you don’t specify a new output directory, UAC may append to an existing one. Use
-oto create a fresh directory for each case.
Tips
- Create a custom profile for your organization’s needs: Copy the default profile and remove artifacts you don’t need to speed up collection and reduce noise.
- Use the
-toption to set a timeout for each artifact collection, preventing hangs on unresponsive systems. - For forensic integrity, write-protect the output directory or use a separate storage device. You can also hash the output files after collection.
- Combine UAC with other tools like
tcpdumporlsoffor a more complete picture, but UAC already includes many of these. - When collecting from a mounted image, ensure the mount is read-only to avoid altering evidence.
- Check the UAC documentation for the full list of artifacts and their descriptions to understand what each file contains.
Troubleshooting
- Permission denied errors: Re-run with
sudo. If you’re already root, check that the output directory is writable. - Python module not found: Install missing dependencies with
pip3 install -r requirements.txt. If you’re offline, download the wheels on another machine and transfer them. - Profile not found: Ensure the profile name is correct and the YAML file exists in the
profilesdirectory. Use--list-profilesto see available ones. - Collection hangs: Some artifact commands may hang (e.g.,
lsofon a busy system). Set a timeout with-t 30to skip after 30 seconds. - Output files are empty: This may happen if the artifact command failed silently. Check the log file in the output directory (e.g.,
uac.log) for errors. - JSON parsing errors: If you’re using
-f jsonand the output isn’t valid JSON, check for encoding issues. Usejqto validate and pretty-print.
Frequently Asked Questions
What is the difference between a profile and an artifact?
A profile is a set of artifact groups that define what to collect. An artifact is a specific piece of data, like user accounts or running processes. Profiles group artifacts for convenience.
Can I collect artifacts from a dead system (disk image)?
Yes, use the -m option to specify the mount point of the image. UAC will treat it as a live filesystem and collect artifacts without executing commands on the original system.
How do I add a custom artifact?
Edit the profile YAML file to add a new artifact definition. You must specify the command to run, the output file name, and optionally a format (e.g., JSON). Then run UAC with that profile.
Does UAC collect memory dumps?
UAC does not collect full memory dumps by default, but it can collect process memory information. For full memory capture, use a dedicated tool like LiME or fmem, then analyze with Volatility.
What output format is best for SIEM integration?
JSON is recommended because it’s structured and can be easily parsed by log management tools. CSV is also usable but less nested.
Is UAC compatible with all Unix-like systems?
UAC supports Linux, macOS, FreeBSD, and other BSD variants. However, some artifacts are OS-specific, so use the matching profile to avoid errors.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.
More cards in this drawer
- Skip Ryobi and Milwaukee? Harbor Freight Tools to Buy
- Funny Subreddits That Make You Laugh
- Why Retro Gaming Is Still Worth Playing Today
- Survival Crafting Game Fatigue: Why & How to Fix It
- Sell Your EV Now Before Prices Plummet?
- KDE Connect Vulnerabilities: Are These Versions at Risk?