Using the Atomic Red Team APIs

Atomic Red Team includes a Ruby API we use to validate atomic tests, generate docs, and interact with ATT&CK.

Ruby API

Atomic Red Team comes with a Ruby API that we use when validating tests again our spec, generating documentation in Markdown format, etc.


Add atomic-red-team to your Gemfile:

gem 'atomic-red-team', git: '', branch: :master

Example: print all the Atomic Tests by ATT&CK technique

require 'atomic_red_team' do |atomic_yaml|
  puts "#{atomic_yaml['attack_technique']}"
  atomic_yaml['atomic_tests'].each do |atomic_test_yaml|
    puts "  #{atomic_test_yaml['name']}"

Example: Show what atomic tests we have for a specific ATT&CK technique

require 'atomic_red_team''T1117').each do |atomic_test_yaml|
  puts "#{atomic_test_yaml['name']}"

For additional examples, see the utilities in bin/ or the API code in atomic_red_team.

Bonus APIs: Ruby ATT&CK API

Atomic Red Team pulls information about ATT&CK techniques using the STIX definitions of ATT&CK located on MITRE’s CTI Github.

We created a lightweight wrapper around that data structure to make it simple to consume. If you would like to use it, install the atomic-red-team gem as described above, and then:

$ bundle exec irb
2.2.0 :001 > require 'attack_api'

Example: Get all the techniques

2.2.0 :020 >
 => 219

Example: Get information about a technique by it’s friendly identifier

2.2.0 :006 >'T1117')
 => {"name"=>"Regsvr32", "description"=>"Regsvr32.exe is a command-line program used to register and unregister
 object linking and embedding controls, including dynamic link libraries (DLLs), on Windows systems. Regsvr32.exe can
 be used to execute arbitrary binaries. (Citation: Microsoft Regsvr32)\n\nAdversaries may take advantage of this
 functionality to proxy" <SNIP> }

2.2.0 :007 >'T1117').keys
 => ["name", "description", "kill_chain_phases", "external_references", "object_marking_refs", "created",
 "created_by_ref", "x_mitre_platforms", "x_mitre_data_sources", "x_mitre_defense_bypassed",
 "x_mitre_permissions_required", "x_mitre_remote_support", "x_mitre_contributors", "id", "modified", "type"]

Example: Get a map of ATT&CK Tactic to all the Techniques associated with it

2.2.0 :019 > {|tactic, techniques| puts "#{tactic} has #{techniques.count} techniques"}
persistence has 56 techniques
defense-evasion has 59 techniques
privilege-escalation has 28 techniques
discovery has 19 techniques
credential-access has 20 techniques
execution has 31 techniques
lateral-movement has 17 techniques
collection has 13 techniques
exfiltration has 9 techniques
command-and-control has 21 techniques
initial-access has 10 techniques

Example: Getting a 2D array of the ATT&CK matrix of Tactic columns and Technique rows:

2.2.0 :062 >
 => ["initial-access", "execution", "persistence", "privilege-escalation", "defense-evasion", "credential-access",
 "discovery", "lateral-movement", "collection", "exfiltration", "command-and-control"]

2.2.0 :071 > {|row| puts row.collect {|technique| technique['name'] if technique}.join(', ')};
Drive-by Compromise, AppleScript, .bash_profile and .bashrc, Access Token Manipulation, Access Token Manipulation, Account Manipulation, Account Discovery, AppleScript, Audio Capture, Automated Exfiltration, Commonly Used Port
Exploit Public-Facing Application, CMSTP, Accessibility Features, Accessibility Features, BITS Jobs, Bash History, Application Window Discovery, Application Deployment Software, Automated Collection, Data Compressed, Communication Through Removable Media
Hardware Additions, Command-Line Interface, AppCert DLLs, AppCert DLLs, Binary Padding, Brute Force, Browser Bookmark Discovery, Distributed Component Object Model, Clipboard Data, Data Encrypted, Connection Proxy
, , Winlogon Helper DLL, , Timestomp, , , , , ,
, , , , Trusted Developer Utilities, , , , , ,
, , , , Valid Accounts, , , , , ,
, , , , Web Service, , , , , ,