diff --git a/README.md b/README.md index f57e255f..3fd4d41b 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ follow the specfication. ### Project status [Travis-CI](https://travis-ci.org/) | [AppVeyor](https://ci.appveyor.com) | [Codecov](https://codecov.io/) ---- | --- | --- +--- | --- | --- [![Build Status](https://travis-ci.org/ForensicArtifacts/artifacts.svg?branch=master)](https://travis-ci.org/ForensicArtifacts/artifacts) | [![Build status](https://ci.appveyor.com/api/projects/status/7gv9fwr269527cj1?svg=true)](https://ci.appveyor.com/project/forensicartifacts/artifacts) | [![codecov](https://codecov.io/gh/ForensicArtifacts/artifacts/branch/master/graph/badge.svg)](https://codecov.io/gh/ForensicArtifacts/artifacts) @@ -20,30 +20,30 @@ follow the specfication. The artifact definitions can be found in the [data directory](https://github.com/ForensicArtifacts/artifacts/tree/master/data) and the format is described in detail in the [Style Guide](https://github.com/ForensicArtifacts/artifacts/blob/master/docs/Artifacts%20definition%20format%20and%20style%20guide.asciidoc). -As of 2015-11-20 the repository contains: +As of 2019-05-11 the repository contains: -| **File paths covered** | **487** | +| **File paths covered** | **1013** | | :------------------ | ------: | -| **Registry keys covered** | **289** | -| **Total artifacts** | **345** | +| **Registry keys covered** | **476** | +| **Total artifacts** | **505** | **Artifacts by type** -| ARTIFACT | COMMAND | DIRECTORY | FILE | PATH | REGISTRY_KEY | REGISTRY_VALUE | WMI | -| :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | -| 14 | 6 | 11 | 191 | 4 | 38 | 65 | 16 | +| ARTIFACT_GROUP | COMMAND | DIRECTORY | FILE | PATH | REGISTRY_KEY | REGISTRY_VALUE | WMI | +| :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | +| 21 | 9 | 14 | 283 | 8 | 46 | 98 | 26 | **Artifacts by OS** -| Darwin | Linux | Windows | -| :---: | :---: | :---: | -| 106 | 75 | 177 | +| Darwin | Linux | Windows | +| :---: | :---: | :---: | +| 33 | 25 | 23 | **Artifacts by label** -| Antivirus | Authentication | Browser | Cloud | Cloud Storage | Configuration Files | External Media | ExternalAccount | IM | Logs | Mail | Network | Software | System | Users | iOS | -| :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | -| 6 | 12 | 18 | 2 | 3 | 34 | 2 | 3 | 4 | 27 | 12 | 7 | 35 | 62 | 59 | 5 | +| Antivirus | Authentication | Browser | Cloud | Cloud Storage | Configuration Files | Docker | External Media | ExternalAccount | Hadoop | History Files | Logs | Mail | Network | Software | System | Users | iOS | +| :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | +| 6 | 18 | 21 | 2 | 4 | 41 | 2 | 2 | 3 | 1 | 3 | 46 | 15 | 14 | 43 | 91 | 68 | 5 | ## Background/History @@ -64,10 +64,8 @@ Please send us your contribution! See [the developers guide](https://github.com/ ## External links -* [ForensicsArtifacts.com ... the definitive database](http://forensicartifacts.com/) * [GRR Artifacts](https://www.blackhat.com/docs/us-14/materials/us-14-Castle-GRR-Find-All-The-Badness-Collect-All-The-Things-WP.pdf), by Greg Castle, Blackhat 2014 ## Contact -[forensicartifacts@googlegroups.com](https://groups.google.com/forum/#!forum/forensicartifacts) - +[slack](https://open-source-dfir.slack.com/messages/CBSJ9TDR9) \ No newline at end of file diff --git a/docs/Artifacts definition format and style guide.asciidoc b/docs/Artifacts definition format and style guide.asciidoc index 6b02e06e..050f9515 100644 --- a/docs/Artifacts definition format and style guide.asciidoc +++ b/docs/Artifacts definition format and style guide.asciidoc @@ -27,6 +27,8 @@ artifacts definitions. | 0.0.3 | J.B. Metz | September 2015 | Additional label. | 0.0.4 | J.B. Metz | July 2016 | Added information about a naming convention. | 0.0.5 | J.B. Metz | February 2019 | Removed returned_types as keyword and format changes. +| 0.0.6 | J. Plum | May 2019 | Add information about the knowledge base, directory sources, +expansion and globbing |=== :numbered: @@ -72,6 +74,12 @@ An object of digital archaeological interest. Where digital archaeology roughly refers to computer forensics without the forensic (legal) context. +=== [[knowledge_base]]Knowledge Base + +The knowledge base is a key value store that is used for storing entries about the host and users. +It is filled via the `provides` attribute of artifacts and can be used in artifact +<> and in <>. + == The artifact definition The best way to show what an artifact definition is, is by example. The @@ -107,7 +115,8 @@ See section: <>. See section: <>. | labels | Optional list of predefined labels. See section: <>. -| provides | Optional list of *TODO* +| provides | Optional list of of strings that describe knowledge base entries that this artifact +# can supply. | supported_os | Optional list that indicates which operating systems the artifact definition applies to. See section: <>. | urls | Optional list of URLs with more contextual information. + @@ -207,6 +216,7 @@ Currently the following different source types are defined: | Value | Description | ARTIFACT_GROUP | A source that consists of a group of other artifacts. | COMMAND | A source that consists of the output of a command. +| DIRECTORY | A source that consists of the contents of directories. | FILE | A source that consists of the contents of files. | PATH | A source that consists of the contents of paths. | REGISTRY_KEY | A source that consists of the contents of Windows Registry keys. @@ -259,6 +269,29 @@ Where `attributes` can contain the following values: | cmd | The path of the command. |=== +=== Directory source + +The directory source is a source that consists of the contents of directories e.g. + +[source,yaml] +---- +- type: DIRECTORY + attributes: + paths: ['%%users.userprofile%%\Downloads\*'] + separator: '\' +---- + +Where `attributes` can contain the following values: + +[cols="1,5",options="header"] +|=== +| Value | Description +| paths | A list of file paths that can potentially be collected. + +The paths can use parameter expansion e.g. `%%environ_systemroot%%`. + +See section: <> +| separator | Optional path seperator e.g. '\' for Windows systems. +|=== + === File source The file source is a source that consists of the contents of files e.g. @@ -278,6 +311,7 @@ Where `attributes` can contain the following values: | paths | A list of file paths that can potentially be collected. + The paths can use parameter expansion e.g. `%%environ_systemroot%%`. + See section: <> +| separator | Optional path seperator e.g. '\' for Windows systems. |=== === Path source @@ -300,6 +334,7 @@ Where `attributes` can contain the following values: | paths | A list of file paths that can potentially be collected. + The paths can use parameter expansion e.g. `%%environ_systemroot%%`. + See section: <> +| separator | Optional path seperator e.g. '\' for Windows systems. |=== === Windows Registry key source @@ -369,6 +404,7 @@ Where `attributes` can contain the following values: | query | The Windows Management Instrumentation (WMI) query. + The query can use parameter expansion e.g. `%%users.username%%`. + See section: <> +| base_object | Optional WMI base object e.g. `winmgmts:\root\SecurityCenter2` |=== == [[conditions]]Conditions @@ -535,5 +571,16 @@ supported_os: [Windows, Linux, Darwin] == [[parameter_expansion]]Parameter expansion and globs -*TODO* +Path, keys, key and query attributes can contain parameter expansion and globing. This allows +for flexible creation of artifact locations. + +Parameter expansions values are enclosed by double percent symbols e.g. `%%environ_systemroot%%`. +The parameter expansion value can be replaced by the corresponding value from the +<>. +Parameter can also contain regular glob elements (such as `**`, `*`, `?`, `[a-z]`). For +example, having files `foo`, `bar`, `baz` glob expansion of `ba?` will yield +`bar` and `baz`. Group expansion allows defining lists of possible artifact locations for example, +given path `foo/{bar,baz}/{quux,norf}` the locations `foo/bar/quux`, `foo/bar/norf`, `foo/baz/quux` +and `foo/baz/norf` are defined. A recursive component (specified as `**`) matches any directory +tree up to some specified depth (3 by default). ** does not match the current directory.