Read in ATT&CK events from a file

This is a convenience wrapper for readr::read_csv() that sets up a contract to read in incident events with some pre-determined expectations. See Details for more information.

read_events(path, matrix = c("enterprise", "mobile", "pre"), ...)

Arguments

path

path to a CSV file that contains ATT&CK events. This will be path.expand()ed.
matrix

which matrix are the events associated with?
...

passed on to readr::read_csv()

Details

While sufficient metadata and helpers have been provided with this package to enable customized use of the ATT&CK matricies sometimes you just want to get stuff done quickly and for that we need to establish some ground rules.

This function defines and "incident event" record as something that contains the fields:

  • event_id: a unique identifier for this event

  • incident_id: the associated incident for the event_id; again, a unique identifier for each incident

  • event_ts: the timestamp for when the event occurred (anything date-like)

  • detection_ts: the timestamp for when the event was detected (anything date-like)

  • tactic: the ATT&CK Tactic; can be in "id" format (dashed lowercase), "pretty" (spaces, titlecase), or "newline" (newlines, titlecase)

  • technique: the ATT&CK Technique id or precise spelling if spelled out

  • discovery_source: free text field (it should still be "identifier-ish") that helps pinpoint which control/logging source enabled discovery of the event.

  • reporting_source: free text field (it should still be "identifier-ish") that identifies what did the reporting for the discovery_source.

  • responder_id the id of the incident reponder associated with this combination of event_id and incident_id.

You can think of discovery_source & reporting_source this way: say the Windows Event Log captured the evidence of a failed (or successful) local admin logon event. It passes that on to your centralized logging facility and/or your SIEM. You can make discovery_source "Windows Event Log" and reporting_source whichever technology you used.

Any column not-present will be turned into NA. Columns not matching the above names will be removed from the object returned.

Examples

# NOT RUN {
read_events(system.file("extdat/sample-incidents.csv.gz", package = "attckr"))
# }