---
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](#bonus-apis-ruby-attck-api). 

## 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. 

### Installing
Add atomic-red-team to your Gemfile:
```ruby
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
```ruby
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
```ruby
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](https://raw.githubusercontent.com/mitre/cti/master/enterprise-attack/enterprise-attack.json).

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](#using-the-atomic-red-team-api),
and then:

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

### Example: Get all the techniques
```ruby
2.2.0 :020 > Attack.new.techniques.count
 => 219
```

### Example: Get information about a technique by it's friendly identifier
```ruby
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
```ruby
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: Getting a 2D array of the ATT&CK matrix of Tactic columns and Technique rows:
```ruby
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, , , , , ,
```