Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update documentation #340

Closed
wants to merge 1 commit into from
Closed

Update documentation #340

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 15 additions & 17 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,38 +12,38 @@ follow the specfication.
### Project status
cugu marked this conversation as resolved.
Show resolved Hide resolved

[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)


## Artifact Definitions

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

Expand All @@ -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

[[email protected]](https://groups.google.com/forum/#!forum/forensicartifacts)

[slack](https://open-source-dfir.slack.com/messages/CBSJ9TDR9)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[email protected] is still valid, undo remove

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it only Google internal? Because I get an access denied (#418) on that page.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's a private (external) Google group, you'll need to subscribe to it

51 changes: 49 additions & 2 deletions docs/Artifacts definition format and style guide.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Knowledge Base is a GRR implementation detail, not part of the specification. One could use runtime environment variables to expands paths.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I used it as an easy way to describe provides and parameter expansion. If that should not be part of the spec those parts have to be defined on another way.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If that should not be part of the spec those parts have to be defined on another way.

that needs to be assessed, currently provides is concept introduced by GRR.


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
<<conditions,conditions>> and in <<parameter_expansion,parameter expansion>>.

== The artifact definition

The best way to show what an artifact definition is, is by example. The
Expand Down Expand Up @@ -107,7 +115,8 @@ See section: <<sources,Sources>>.
See section: <<conditions,Conditions>>.
| labels | Optional list of predefined labels.
See section: <<labels,Labels>>.
| 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: <<supported_os,Supported operating system>>.
| urls | Optional list of URLs with more contextual information. +
Expand Down Expand Up @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Future of DIRECTORY depends on #286

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But is it currently part of the spec? It is a used in 14 artifact definitions.

| 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.
Expand Down Expand Up @@ -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: <<parameter_expansion,Parameter expansion and globs>>
| 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.
Expand All @@ -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: <<parameter_expansion,Parameter expansion and globs>>
| separator | Optional path seperator e.g. '\' for Windows systems.
cugu marked this conversation as resolved.
Show resolved Hide resolved
|===

=== Path source
Expand All @@ -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: <<parameter_expansion,Parameter expansion and globs>>
| separator | Optional path seperator e.g. '\' for Windows systems.
|===

=== Windows Registry key source
Expand Down Expand Up @@ -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: <<parameter_expansion,Parameter expansion and globs>>
| base_object | Optional WMI base object e.g. `winmgmts:\root\SecurityCenter2`
|===

== [[conditions]]Conditions
Expand Down Expand Up @@ -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
<<knowledge_base,knowledge base>>.

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,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Group expansion is currently not supported.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But is it part of the spec?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not at this point

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
cugu marked this conversation as resolved.
Show resolved Hide resolved
tree up to some specified depth (3 by default). ** does not match the current directory.