atomic-red-team/docs/apis-execution-frameworks.md

layout

layout
default

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.

Want to contribute APIs for another language such as Python or Powershell? Follow the interface in atomic_red_team/atomic_red_team.rb and submit a pull request!

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. You too can use the API to use Atomic Red Team tests in your test execution framework.

Installing

Add atomic-red-team to your Gemfile:

gem 'atomic-red-team', git: 'git@github.com:redcanaryco/atomic-red-team.git', branch: :master

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

require 'atomic_red_team'

AtomicRedTeam.new.atomic_tests.each do |atomic_yaml|
  puts "#{atomic_yaml['attack_technique']}"
  atomic_yaml['atomic_tests'].each do |atomic_test_yaml|
    puts "  #{atomic_test_yaml['name']}"
  end
end

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

require 'atomic_red_team'

AtomicRedTeam.new.atomic_tests_for_technique('T1117').each do |atomic_test_yaml|
  puts "#{atomic_test_yaml['name']}"
end

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 > Attack.new.techniques.count
 => 219

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

2.2.0 :006 >   Attack.new.technique_info('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 > Attack.new.technique_info('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 > Attack.new.techniques_by_tactic.each {|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 (my favorite): Getting a 2D array of the ATT&CK matrix of Tactic columns and Technique rows:

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

2.2.0 :071 > Attack.new.ordered_tactic_to_technique_matrix.each {|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
<SNIP>
, , Winlogon Helper DLL, , Timestomp, , , , , ,
, , , , Trusted Developer Utilities, , , , , ,
, , , , Valid Accounts, , , , , ,
, , , , Web Service, , , , , ,