Skip to content

Commit 18a6307

Browse files
Cyb3rWard0gCyb3rWard0g
committed
0.2.3 Release and Docs
+ Re-wrote the STIX mapping to translate fields to a friendly schema + Set all functions to return a STIX object + Added stix_format parameter to return a dictionary with the friendly schema if needed + Updated Notebooks
1 parent 25a6966 commit 18a6307

17 files changed

+7914
-42464
lines changed

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,8 @@ The project is currently in a beta stage, which means that the code and the func
2626

2727
# Getting Started
2828

29+
[Attackcti Docs](https://attackcti.readthedocs.io/en/latest/)
30+
2931
## Requirements
3032

3133
Python 3+

‎attackcti/attack_api.py‎

Lines changed: 647 additions & 568 deletions
Large diffs are not rendered by default.

‎docs/Makefile‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = sphinx-build
7+
SOURCEDIR = source
8+
BUILDDIR = build
9+
10+
# Put it first so that "make" without argument is like "make help".
11+
help:
12+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
13+
14+
.PHONY: help Makefile
15+
16+
# Catch-all target: route all unknown targets to Sphinx using the new
17+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
18+
%: Makefile
19+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/make.bat‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
13+
if "%1" == "" goto help
14+
15+
%SPHINXBUILD% >NUL 2>NUL
16+
if errorlevel 9009 (
17+
echo.
18+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
19+
echo.installed, then set the SPHINXBUILD environment variable to point
20+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
21+
echo.may add the Sphinx directory to PATH.
22+
echo.
23+
echo.If you don't have Sphinx installed, grab it from
24+
echo.http://sphinx-doc.org/
25+
exit /b 1
26+
)
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
33+
34+
:end
35+
popd

‎docs/source/attackcti_overview.rst‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
ATTACK CTI Overview
2+
===================
3+
4+
The ATTACK-Python-Client project provides a python library named ``attackcti`` which wraps the functionality of `cti-python-stix2 <https://github.com/oasis-open/cti-python-stix2>`_ and `cti-taxii-client <https://github.com/oasis-open/cti-taxii-client>`_ libraries developed by MITRE.
5+
This python wrapper allows ATT&CK users to query STIX content from the ATT&CK public TAXII server via pre-defined functions with a few lines of code.
6+
7+
Requirements
8+
############
9+
10+
* Python3
11+
12+
Installation
13+
############
14+
15+
The ``attackcti`` library can be installed via PIP:
16+
17+
.. code-block:: console
18+
19+
$ pip install attackcti
20+
21+
Or you can install it from source:
22+
23+
.. code-block:: console
24+
25+
$ git clone https://github.com/Cyb3rWard0g/ATTACK-Python-Client
26+
$ cd ATTACK-Python-Client
27+
$ pip install .
28+
29+
Quick Start
30+
###########
31+
32+
You can simply import the ``attackcti`` library and start retrieving ATT&CK content in STIX from its public TAXII server::
33+
34+
>>> from attackcti import attack_client
35+
>>>
36+
>>> lift = attack_client()
37+
>>> all_enterprise = lift.get_all_enterprise()
38+
>>>
39+
>>> len(all_enterprise)
40+
10
41+
>>>
42+
>>> all_enterprise.keys()
43+
dict_keys(['techniques', 'mitigations', 'groups', 'malware', 'tools', 'relationships', 'tactics', 'matrix', 'identity', 'marking-definition'])
44+
>>>
45+
>>> len(all_enterprise['techniques'])
46+
244
47+
>>>
48+
>>> all_enterprise["techniques"][0]
49+
AttackPattern(
50+
type='attack-pattern',
51+
id='attack-pattern--cf7b3a06-8b42-4c33-bbe9-012120027925',
52+
created_by_ref='identity--c78cb6e5-0c4b-4611-8297-d1b8b55e40b5',
53+
created='2019-04-25T20:53:07.719Z',
54+
modified='2019-04-29T21:13:49.686Z',
55+
name='Compile After Delivery',
56+
description='Adversaries may attempt to make payloads difficult to discover and analyze by delivering files to victims as uncompiled code. Similar to [Obfuscated Files or Information](https://attack.mitre.org/techniques/T1027), text-based source code files may subvert analysis and scrutiny from protections targeting executables/binaries. These payloads will need to be compiled before execution; typically via native utilities such as csc.exe or GCC/MinGW.(Citation: ClearSky MuddyWater Nov 2018)\n\nSource code payloads may also be encrypted, encoded, and/or embedded within other files, such as those delivered as a [Spearphishing Attachment](https://attack.mitre.org/techniques/T1193). Payloads may also be delivered in formats unrecognizable and inherently benign to the native OS (ex: EXEs on macOS/Linux) before later being (re)compiled into a proper executable binary with a bundled compiler and execution framework.(Citation: TrendMicro WindowsAppMac)\n',
57+
kill_chain_phases=[KillChainPhase
58+
(
59+
kill_chain_name='mitre-attack',
60+
phase_name='defense-evasion'
61+
)],
62+
external_references=[
63+
ExternalReference
64+
(
65+
source_name='mitre-attack',
66+
url='https://attack.mitre.org/techniques/T1500',
67+
external_id='T1500'
68+
),
69+
ExternalReference
70+
(
71+
source_name='ClearSky MuddyWater Nov 2018',
72+
description='ClearSky Cyber Security. (2018, November). MuddyWater Operations in Lebanon and Oman: Using an Israeli compromised domain for a two-stage campaign. Retrieved November 29, 2018.',
73+
url='https://www.clearskysec.com/wp-content/uploads/2018/11/MuddyWater-Operations-in-Lebanon-and-Oman.pdf'
74+
),
75+
ExternalReference
76+
(
77+
source_name='TrendMicro WindowsAppMac',
78+
description='Trend Micro. (2019, February 11). Windows App Runs on Mac, Downloads Info Stealer and Adware. Retrieved April 25, 2019.',
79+
url='https://blog.trendmicro.com/trendlabs-security-intelligence/windows-app-runs-on-mac-downloads-info-stealer-and-adware/'
80+
)
81+
],
82+
object_marking_refs=['marking-definition--fa42a846-8d90-4e51-bc29-71d5b4802168'],
83+
x_mitre_contributors=['Ye Yint Min Thu Htut, Offensive Security Team, DBS Bank', 'Praetorian'],
84+
x_mitre_data_sources=['Process command-line parameters','Process monitoring', 'File monitoring'],
85+
x_mitre_defense_bypassed=['Static File Analysis', 'Binary Analysis', 'Anti-virus', 'Host intrusion prevention systems', 'Signature-based detection'],
86+
x_mitre_detection='Monitor the execution file paths and command-line arguments for common compilers, such as csc.exe and GCC/MinGW, and correlate with other suspicious behavior to reduce false positives from normal user and administrator behavior. The compilation of payloads may also generate file creation and/or file write events. Look for non-native binary formats and cross-platform compiler and execution frameworks like Mono and determine if they have a legitimate purpose on the system.(Citation: TrendMicro WindowsAppMac) Typically these should only be used in specific and limited cases, like for software development.',
87+
x_mitre_permissions_required=['User'],
88+
x_mitre_platforms=['Linux', 'macOS', 'Windows'],
89+
x_mitre_system_requirements=['Compiler software (either native to the system or delivered by the adversary)'],
90+
x_mitre_version='1.0'
91+
)
92+
93+
By default, the data returned by the available functions in the attackcti library is of type ``stix2``::
94+
95+
>>> type(all_enterprise['techniques'][0])
96+
<class 'stix2.v20.sdo.AttackPattern'>
97+
98+
However, you can use the available ``stix_format`` parameter and set it to ``False`` to return a dictionary and with a more friendly field name schema as shown below::
99+
100+
>>> all_enterprise_friendly = lift.get_all_enterprise(stix_format=False)
101+
>>>
102+
>>> type(all_enterprise_friendly['techniques'][0])
103+
<class 'dict'>
104+
>>>
105+
>>> len(all_enterprise_friendly['techniques'])
106+
244
107+
>>>
108+
>>> all_enterprise_friendly['techniques'][0]
109+
{
110+
'external_references': [
111+
{
112+
'external_id': 'T1500',
113+
'source_name': 'mitre-attack',
114+
'url': 'https://attack.mitre.org/techniques/T1500'
115+
},
116+
{
117+
'url': 'https://www.clearskysec.com/wp-content/uploads/2018/11/MuddyWater-Operations-in-Lebanon-and-Oman.pdf',
118+
'source_name': 'ClearSky MuddyWater Nov 2018', 'description': 'ClearSky Cyber Security. (2018, November). MuddyWater Operations in Lebanon and Oman: Using an Israeli compromised domain for a two-stage campaign. Retrieved November 29, 2018.'
119+
},
120+
{
121+
'url': 'https://blog.trendmicro.com/trendlabs-security-intelligence/windows-app-runs-on-mac-downloads-info-stealer-and-adware/',
122+
'source_name': 'TrendMicro WindowsAppMac',
123+
'description': 'Trend Micro. (2019, February 11). Windows App Runs on Mac, Downloads Info Stealer and Adware. Retrieved April 25, 2019.'
124+
}
125+
],
126+
'kill_chain_phases': [
127+
{
128+
'phase_name': 'defense-evasion',
129+
'kill_chain_name': 'mitre-attack'
130+
}
131+
],
132+
'x_mitre_version': '1.0',
133+
'url': 'https://attack.mitre.org/techniques/T1500',
134+
'matrix': 'mitre-attack',
135+
'technique_id': 'T1500',
136+
'object_marking_refs': ['marking-definition--fa42a846-8d90-4e51-bc29-71d5b4802168'],
137+
'type': 'attack-pattern',
138+
'modified': '2019-04-29T21:13:49.686Z',
139+
'created_by_ref': 'identity--c78cb6e5-0c4b-4611-8297-d1b8b55e40b5',
140+
'tactic': 'defense-evasion',
141+
'id': 'attack-pattern--cf7b3a06-8b42-4c33-bbe9-012120027925',
142+
'technique': 'Compile After Delivery',
143+
'created': '2019-04-25T20:53:07.719Z',
144+
'technique_description': 'Adversaries may attempt to make payloads difficult to discover and analyze by delivering files to victims as uncompiled code. Similar to [Obfuscated Files or Information](https://attack.mitre.org/techniques/T1027), text-based source code files may subvert analysis and scrutiny from protections targeting executables/binaries. These payloads will need to be compiled before execution; typically via native utilities such as csc.exe or GCC/MinGW.(Citation: ClearSky MuddyWater Nov 2018)\n\nSource code payloads may also be encrypted, encoded, and/or embedded within other files, such as those delivered as a [Spearphishing Attachment](https://attack.mitre.org/techniques/T1193). Payloads may also be delivered in formats unrecognizable and inherently benign to the native OS (ex: EXEs on macOS/Linux) before later being (re)compiled into a proper executable binary with a bundled compiler and execution framework.(Citation: TrendMicro WindowsAppMac)\n',
145+
'contributors': ['Ye Yint Min Thu Htut, Offensive Security Team, DBS Bank', 'Praetorian'],
146+
'permissions_required': ['User'],
147+
'data_sources': ['Process command-line parameters', 'Process monitoring', 'File monitoring'],
148+
'technique_detection': 'Monitor the execution file paths and command-line arguments for common compilers, such as csc.exe and GCC/MinGW, and correlate with other suspicious behavior to reduce false positives from normal user and administrator behavior. The compilation of payloads may also generate file creation and/or file write events. Look for non-native binary formats and cross-platform compiler and execution frameworks like Mono and determine if they have a legitimate purpose on the system.(Citation: TrendMicro WindowsAppMac) Typically these should only be used in specific and limited cases, like for software development.',
149+
'platform': ['Linux', 'macOS', 'Windows'],
150+
'system_requirements': ['Compiler software (either native to the system or delivered by the adversary)'],
151+
'defense_bypassed': ['Static File Analysis', 'Binary Analysis', 'Anti-virus', 'Host intrusion prevention systems', 'Signature-based detection']
152+
}
153+
154+
Notebooks
155+
#########
156+
157+
I put together a few Jupyte notebooks for you to learn a little bit more about a few of the functions available in the ``attackcti`` library:
158+
159+
* `Notebooks <https://github.com/Cyb3rWard0g/ATTACK-Python-Client/tree/master/notebooks>`_

0 commit comments

Comments
 (0)