Some code cleanup related to artifact merging (#120)

.changes/unreleased/Changed-20240306-000026.yaml

@@ -1,4 +1,5 @@
 kind: Changed
-body: Combined macOS and Linux artifacts. Can parse both macOS and Linux artifacts
- on either OS
+body:
+ Combined all supported forensic artifacts. Can parse all supported forensic artifacts
+ on any OS that can run artemis
 time: 2024-03-06T00:00:26.777380959-05:00

.justfile

@@ -76,7 +76,7 @@ nextest:(_wasm)
 cli:
  cd cli && cargo build --release
 
-# Just build artemis-core
+# Just build core library
 core:
  cd artemis-core && cargo build --release
 

ARCHITECTURE.md

@@ -0,0 +1,35 @@
+# Artemis architecture
+
+This document provides a very high level overview of the artemis code
+architecture. Inspired by
+https://matklad.github.io//2021/02/06/ARCHITECTURE.md.html
+
+A more detailed overview can be found at
+https://puffycid.github.io/artemis-api/docs/Contributing/overview
+
+### Artemis repo structure
+
+The artemis repository is composed of multiple workspaces
+
+- `cli/` - Contains the code the powers the CLI application
+- `core/` - Contains the code related to all forensic parsers and the Deno (JS)
+ runtime
+- `common/` - Collection of structs shared between workspaces
+- `server/` - Experimental server component for artemis. This code is not
+ included in GitHub releases
+- `webui/` - Experimental webUI for the server. This code is not included in
+ GitHub releases
+
+### Core structure
+
+The `core` crate (also sometimes referred to as `artemis-core`) is primarily
+grouped by forensic artifacts based on the OS.
+
+- `artifacts/` - Contains all the code associated with parsing forensic
+ artifacts. The bulk of artemis code is located here. It is further broken down
+ by OS.
+- `filesystem/` - Contains helper functions to access the filesystem
+- `output/` - Code related to outputting the forensic artifacts
+- `runtime/` - Code related to the Deno (JS) runtime
+- `structs/` - Collection of structs used by `core` crate
+- `utils/` - Contains misc helper functions

Cargo.toml

@@ -1,5 +1,5 @@
 [workspace]
-members = ["cli", "artemis-core", "server", "webui", "common"]
+members = ["cli", "core", "server", "webui", "common"]
 resolver = "2"
 
 [profile.release]

README.md

@@ -15,8 +15,6 @@ Notable features _so far_:
 - Output to JSON or JSONL file(s)
 - Can output results to local system or upload to cloud services.
 - Embedded JavaScript runtime via [Deno](https://deno.land/)
-- Can be used as a library
-- MIT license
 
 Checkout the online guide at https://puffycid.github.io/artemis-api for indepth
 walkthrough on using artemis
@@ -59,19 +57,43 @@ Commands:
  chromiumhistory Parse Chromium History
  firefoxdownloads Parse Firefox Downloads
  chromiumdownloads Parse Chromium Downloads
- shellhistory Parse Shellhistory
- cron Parse Cron Jobs
- sudologs Grab Sudo logs
- execpolicy Parse ExecPolicy
- users Collect local users
- fsevents Parse FsEvents entries
- emond Parse Emond persistence. Removed in Ventura
- loginitems Parse LoginItems
- launchd Parse Launch Daemons and Agents
- groups Collect local groups
- safarihistory Collect Safari History
- safaridownloads Collect Safari Downloads
- unifiedlogs Parse the Unified Logs
+ prefetch Parse Prefetch
+ eventlogs windows: Parse EventLogs
+ rawfilelisting windows: Parse NTFS to get filelisting
+ shimdb windows: Parse ShimDatabase
+ registry windows: Parse Registry
+ userassist windows: Parse Userassist
+ shimcache windows: Parse Shimcache
+ shellbags windows: Parse Shellbags
+ amcache windows: Parse Amcache
+ shortcuts windows: Parse Shortcuts
+ usnjrnl windows: Parse UsnJrnl
+ bits windows: Parse BITS
+ srum windows: Parse SRUM
+ users-windows windows: Parse Users
+ search windows: Parse Windows Search
+ tasks windows: Parse Windows Tasks
+ services windows: Parse Windows Services
+ jumplists windows: windows: Parse Jumplists
+ recyclebin windows: Parse RecycleBin
+ wmipersist windows: Parse WMI Repository
+ execpolicy macos: Parse ExecPolicy
+ users-macos macos: Collect local users
+ fsevents macos: Parse FsEvents entries
+ emond macos: Parse Emond persistence. Removed in Ventura
+ loginitems macos: Parse LoginItems
+ launchd macos: Parse Launch Daemons and Agents
+ groups-macos macos: Collect local groups
+ safari-history macos: Collect Safari History
+ safari-downloads macos: Collect Safari Downloads
+ unifiedlogs macos: Parse the Unified Logs
+ sudologs-macos macos: Parse Sudo log entries from Unified Logs
+ spotlight macos: Parse the Spotlight database
+ shellhistory unix: Parse Shellhistory
+ cron unix: Parse Cron Jobs
+ sudologs-linux linux: Grab Sudo logs
+ journals linux: Parse systemd Journal files
+ logons linux: Parse Logon files
  help Print this message or the help of the given subcommand(s)
 
 Options:

cli/Cargo.toml

@@ -7,5 +7,5 @@ license = "MIT"
 [dependencies]
 base64 = { workspace = true }
 log = { workspace = true }
-artemis-core = { path = "../artemis-core" }
+core = { path = "../core" }
 clap = { version = "4.5.2", features = ["std", "help", "derive"] }

cli/src/collector/mod.rs

@@ -1,2 +1,2 @@
 pub(crate) mod commands;
-pub(crate) mod macos;
+pub(crate) mod system;

cli/src/collector/macos.rs → cli/src/collector/system.rs

@@ -1,5 +1,6 @@
 use super::commands::CommandArgs;
-use artemis_core::{
+use clap::{arg, Subcommand};
+use core::{
  core::artemis_collection,
  structs::{
  artifacts::os::{
@@ -22,7 +23,6 @@ use artemis_core::{
  toml::{ArtemisToml, Artifacts, Output},
  },
 };
-use clap::{arg, Subcommand};
 
 #[derive(Subcommand)]
 pub(crate) enum Commands {
@@ -38,8 +38,15 @@ pub(crate) enum Commands {
 
 /// Run the collector and parse specified artifacts
 pub(crate) fn run_collector(command: &Commands, output: Output) {
+ #[cfg(target_os = "macos")]
+ let system = String::from("macos");
+ #[cfg(target_os = "linux")]
+ let system = String::from("linux");
+ #[cfg(target_os = "windows")]
+ let system = String::from("windows");
+
  let mut collector = ArtemisToml {
- system: String::from("macos"),
+ system,
  output,
  artifacts: Vec::new(),
  };
@@ -67,7 +74,7 @@ pub(crate) fn run_collector(command: &Commands, output: Output) {
  artemis_collection(&mut collector).unwrap();
 }
 
-/// Setup any artifact options. Only a few have options on macOS
+/// Setup any artifact options
 fn setup_artifact(artifact: &CommandArgs) -> Artifacts {
  let mut collect = Artifacts {
  artifact_name: String::new(),
@@ -444,15 +451,15 @@ fn setup_artifact(artifact: &CommandArgs) -> Artifacts {
 #[cfg(test)]
 mod tests {
  use super::{run_collector, setup_artifact, Commands};
- use crate::collector::macos::CommandArgs::{
+ use crate::collector::system::CommandArgs::{
  Amcache, Bits, Chromiumdownloads, Chromiumhistory, Cron, Emond, Eventlogs, Execpolicy,
  Filelisting, Firefoxdownloads, Firefoxhistory, Fsevents, GroupsMacos, Journals, Jumplists,
  Launchd, Loginitems, Logons, Prefetch, Processes, Rawfilelisting, Recyclebin, Registry,
  SafariDownloads, SafariHistory, Services, Shellbags, Shellhistory, Shimcache, Shimdb,
  Spotlight, Srum, SudologsLinux, SudologsMacos, Systeminfo, Tasks, Unifiedlogs, UsersMacos,
  UsersWindows,
  };
- use artemis_core::structs::toml::Output;
+ use core::structs::toml::Output;
  fn output() -> Output {
  let out = Output {
  name: String::from("local_collector"),

cli/src/main.rs

@@ -1,8 +1,8 @@
-use crate::collector::macos::run_collector;
-use artemis_core::structs::toml::Output;
+use crate::collector::system::run_collector;
 use base64::{engine::general_purpose, Engine};
 use clap::Parser;
-use collector::macos::Commands;
+use collector::system::Commands;
+use core::structs::toml::Output;
 use log::info;
 mod collector;
 
@@ -36,7 +36,7 @@ fn parse_args(args: &Args) {
 
  if let Some(toml) = &args.toml {
  if !toml.is_empty() {
- let collection_results = artemis_core::core::parse_toml_file(toml);
+ let collection_results = core::core::parse_toml_file(toml);
  match collection_results {
  Ok(_) => info!("[artemis] Collection success"),
  Err(err) => {
@@ -57,7 +57,7 @@ fn parse_args(args: &Args) {
  return;
  }
  };
- let collection_results = artemis_core::core::parse_toml_data(&toml_data);
+ let collection_results = core::core::parse_toml_data(&toml_data);
  match collection_results {
  Ok(_) => info!("[artemis] Collection success"),
  Err(err) => {
@@ -68,7 +68,7 @@ fn parse_args(args: &Args) {
  }
  } else if let Some(js) = &args.javascript {
  if !js.is_empty() {
- let collection_results = artemis_core::core::parse_js_file(js);
+ let collection_results = core::core::parse_js_file(js);
  match collection_results {
  Ok(_) => info!("[artemis] JavaScript execution success"),
  Err(err) => {
@@ -193,7 +193,7 @@ mod tests {
  #[cfg(target_os = "macos")]
  fn test_parse_args_command_macos() {
  use crate::collector::commands::CommandArgs::Filelisting;
- use crate::collector::macos::Commands;
+ use crate::collector::system::Commands;
 
  let args = Args {
  toml: None,
@@ -219,7 +219,7 @@ mod tests {
  #[test]
  #[cfg(target_os = "windows")]
  fn test_parse_args_command_windows() {
- use crate::collector::{commands::CommandArgs::Shortcuts, macos::Commands};
+ use crate::collector::{commands::CommandArgs::Shortcuts, system::Commands};
  let args = Args {
  toml: None,
  decode: None,
@@ -239,7 +239,7 @@ mod tests {
  #[cfg(target_os = "linux")]
  fn test_parse_args_command_linux() {
  use crate::collector::commands::CommandArgs::Processes;
- use crate::collector::macos::Commands;
+ use crate::collector::system::Commands;
 
  let args = Args {
  toml: None,

artemis-core/Cargo.toml → core/Cargo.toml

@@ -1,5 +1,5 @@
 [package]
-name = "artemis-core"
+name = "core"
 edition = { workspace = true }
 version = { workspace = true }
 license = "MIT"

artemis-core/benches/bits_benchmark.rs → core/benches/bits_benchmark.rs

@@ -1,4 +1,4 @@
-use artemis_core::core::parse_toml_file;
+use core::core::parse_toml_file;
 use criterion::{criterion_group, criterion_main, Criterion};
 use std::path::PathBuf;