Merge pull request #26 from swimlane/0_6_0_release

0.6.0 Release

.github/workflows/macos.yml

@@ -9,7 +9,7 @@ jobs:
     runs-on: macos-latest
     strategy:
       matrix:
-        python-version: [3.6, 3.7, 3.8, 3.9]
+        python-version: [3.7, 3.8, 3.9]
 
     steps:
     - uses: actions/checkout@v2

CHANGELOG.md

@@ -1,5 +1,10 @@
 # CHANGELOG
 
+## 0.6.0 - 2021-12-17
+
+    * Updated documentation
+    * Added better handling of help
+
 ## 0.5.1 - 2021-11-18
 
     * Updating handling of passing --help to the run command

README.md

@@ -29,6 +29,8 @@ Additionally, `atomic-operator` can be used in many other situations like:
 * Can prompt for input arguments but not required
 * Assist with downloading the atomic-red-team repository
 * Can be automated further based on a configuration file
+* A command-line and importable Python package
+* Plus more
 
 ## Getting Started
 
@@ -45,6 +47,7 @@ The next steps will guide you through setting up and running `atomic-operator`.
 * [Get Atomics](docs/atomics.md) Install / clone Atomic Red Team repository
 * [atomic-operator](docs/atomic-operator.md) Understand the options availble in atomic-operator
 * [Running Test on Command Line](docs/running-tests-command-line.md) or [Running Tests within a Script](docs/running-tests-script.md)
+* [Running Tests via Configuration File](atomic-operator-config.md)
 
 ## Installation
 
@@ -124,6 +127,35 @@ You can see additional parameters by running the following command:
 atomic-operator run -- --help
 ```
 
+
+
+|Parameter Name|Type|Default|Description|
+|--------------|----|-------|-----------|
+|techniques|list|all|One or more defined techniques by attack_technique ID.|
+|test_guids|list|None|One or more Atomic test GUIDs.|
+|atomics_path|str|os.getcwd()|The path of Atomic tests.|
+|check_prereqs|bool|False|Whether or not to check for prereq dependencies (prereq_comand).|
+|get_prereqs|bool|False|Whether or not you want to retrieve prerequisites.|
+|cleanup|bool|False|Whether or not you want to run cleanup command(s).|
+|copy_source_files|bool|True|Whether or not you want to copy any related source (src, bin, etc.) files to a remote host.|
+|command_timeout|int|20|Time duration for each command before timeout.|
+|debug|bool|False|Whether or not you want to output details about tests being ran.|
+|prompt_for_input_args|bool|False|Whether you want to prompt for input arguments for each test.|
+|return_atomics|bool|False|Whether or not you want to return atomics instead of running them.|
+|config_file|str|None|A path to a conifg_file which is used to automate atomic-operator in environments.|
+|hosts|list|None|A list of one or more remote hosts to run a test on.|
+|username|str|None|Username for authentication of remote connections.|
+|password|str|None|Password for authentication of remote connections.|
+|ssh_key_path|str|None|Path to a SSH Key for authentication of remote connections.|
+|private_key_string|str|None|A private SSH Key string used for authentication of remote connections.|
+|verify_ssl|bool|False|Whether or not to verify ssl when connecting over RDP (windows).|
+|ssh_port|int|22|SSH port for authentication of remote connections.|
+|ssh_timeout|int|5|SSH timeout for authentication of remote connections.|
+|**kwargs|dict|None|If additional flags are passed into the run command then we will attempt to match them with defined inputs within Atomic tests and replace their value with the provided value.|
+
+
+
+
 You should see a similar output to the following:
 
 ```text

atomic_operator/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.5.4"
+__version__ = "0.6.0"
 
 
 from .atomic_operator import AtomicOperator

atomic_operator/__main__.py

@@ -5,7 +5,8 @@ def main():
     atomic_operator = AtomicOperator()
     fire.Fire({
         'run': atomic_operator.run,
-        'get_atomics': atomic_operator.get_atomics
+        'get_atomics': atomic_operator.get_atomics,
+        'help': atomic_operator.help
     })
 
 if __name__ == "__main__":

atomic_operator/atomic_operator.py

@@ -126,6 +126,12 @@ def __run_technique(self, technique, **kwargs):
                     'technique_name': technique.display_name
                 })
 
+    def help(self, method=None):
+        from fire.trace import FireTrace
+        from fire.helptext import HelpText
+        obj = AtomicOperator if not method else getattr(self, method)
+        return HelpText(self.run,trace=FireTrace(obj))
+
     def get_atomics(self, desintation=os.getcwd(), **kwargs):
         """Downloads the RedCanary atomic-red-team repository to your local system.
 
@@ -146,7 +152,7 @@ def run(self, techniques: list=['all'], test_guids: list=[], atomics_path=os.get
                   command_timeout=20, debug=False, prompt_for_input_args=False,
                   return_atomics=False, config_file=None, hosts=[], username=None,
                   password=None, ssh_key_path=None, private_key_string=None,
-                  verify_ssl=False, ssh_port=22, ssh_timeout=5, **kwargs) -> None:
+                  verify_ssl=False, ssh_port=22, ssh_timeout=5, *args, **kwargs) -> None:
         """The main method in which we run Atomic Red Team tests.
 
         Args:
@@ -176,8 +182,7 @@ def run(self, techniques: list=['all'], test_guids: list=[], atomics_path=os.get
             ValueError: If a provided technique is unknown we raise an error.
         """
         if kwargs.get('help'):
-            self.__logger.info("Looks like you tried to run help. Please run 'atomic-operator run -- --help'")
-            return
+            return self.help(method='run')
         if debug:
             import logging
             logging.getLogger().setLevel(logging.DEBUG)

docs/CHANGELOG.md

@@ -1,5 +1,21 @@
 # CHANGELOG
 
+## 0.6.0 - 2021-12-17
+
+    * Updated documentation
+    * Added better handling of help
+
+## 0.5.1 - 2021-11-18
+
+    * Updating handling of passing --help to the run command
+    * Updated docs to reflect change
+
+## 0.5.0 - 2021-11-19
+
+    * Updated and expanded tests
+    * Added CI to build docs and deploy to pypi
+    * Updated localrunner to support windows based on changes made previously
+
 ## 0.4.0 - 2021-11-15
 
     * Added support for transferring files during remote execution

docs/atomic-operator-config.md

@@ -0,0 +1,107 @@
+# Configuration
+
+One feature of `atomic-operator` is the ability to automate running of Atomics even further via a configuration file. The configuration file supports many different layouts for configuration but the major features are:
+
+* Define one or more Atomic tests by GUID 
+  * You can provide values for any defined input arguments for an Atomic test
+  * You can assign an Atomic test to one or more `inventory` objects
+* Define none, one, or more `inventory` objects
+  * An inventory is a collection of authentication properties as well as hosts associated with said authentication credentials
+
+With this structure you can create an inventory group of 1 or 100 hosts using a set of credentials and tell `atomic-operator` to run 1 or more tests with defined inputs against those hosts - infinitely flexible.
+
+Below is an example of all of these features implemented in a configuration file.
+
+```yaml
+inventory:
+  windows1:
+    executor: powershell # or cmd
+    authentication:
+      username: username
+      password: some_passowrd!
+      verify_ssl: false
+    hosts:
+      - 192.168.1.1
+      - 10.32.1.1
+      # etc
+  linux1:
+    executor: ssh
+    authentication:
+      username: username
+      password: some_passowrd!
+      #ssk_key_path:
+      port: 22
+      timeout: 5
+    hosts:
+      - 192.168.1.1
+      - 10.32.100.1
+      # etc.
+atomic_tests:
+  - guid: f7e6ec05-c19e-4a80-a7e7-241027992fdb
+    input_arguments:
+      output_file:
+        value: custom_output.txt
+      input_file:
+        value: custom_input.txt
+    inventories:
+      - windows1
+  - guid: 3ff64f0b-3af2-3866-339d-38d9791407c3
+    input_arguments:
+      second_arg:
+        value: SWAPPPED argument
+    inventories:
+      - windows1
+      - linux1
+  - guid: c141bbdb-7fca-4254-9fd6-f47e79447e17
+    inventories:
+      - linux1
+```
+
+At the basic level of the configuration file you can simply just have one that defines a set of Atomic tests you want to run like so:
+
+```yaml
+atomic_tests:
+  - guid: f7e6ec05-c19e-4a80-a7e7-241027992fdb
+  - guid: 3ff64f0b-3af2-3866-339d-38d9791407c3
+  - guid: c141bbdb-7fca-4254-9fd6-f47e79447e17
+```
+
+You can also specify input variable values for one or more of them:
+
+```yaml
+atomic_tests:
+  - guid: f7e6ec05-c19e-4a80-a7e7-241027992fdb
+    input_arguments:
+      output_file:
+        value: custom_output.txt
+      input_file:
+        value: custom_input.txt
+  - guid: 3ff64f0b-3af2-3866-339d-38d9791407c3
+  - guid: c141bbdb-7fca-4254-9fd6-f47e79447e17
+```
+
+But if you want to run them remotely then you must add in `inventory` objects with the correct credentials and one or more hosts:
+
+```yaml
+inventory:
+  windows1:
+    executor: powershell # or cmd
+    authentication:
+      username: username
+      password: some_passowrd!
+      verify_ssl: false
+    hosts:
+      - 192.168.1.1
+      - 10.32.1.1
+atomic_tests:
+  - guid: f7e6ec05-c19e-4a80-a7e7-241027992fdb
+    input_arguments:
+      output_file:
+        value: custom_output.txt
+      input_file:
+        value: custom_input.txt
+    inventories:
+      - windows1
+  - guid: 3ff64f0b-3af2-3866-339d-38d9791407c3
+  - guid: c141bbdb-7fca-4254-9fd6-f47e79447e17
+```

docs/atomic-operator.md

@@ -120,52 +120,7 @@ FLAGS
 
 ### Running atomic-operator using a config_file
 
-In addition to the ability to pass in parameters with `atomic-operator` you can also pass in a path to a `config_file` that contains all the atomic tests and their potential inputs. You can see an example of this config_file here:
-
-```yaml
-inventory:
-  windows1:
-    executor: powershell # or cmd
-    input:
-      username: username
-      password: some_passowrd!
-      verify_ssl: false
-    hosts:
-      - 192.168.1.1
-      - 10.32.1.1
-      # etc
-  linux1:
-    executor: ssh
-    authentication:
-      username: username
-      password: some_passowrd!
-      #ssk_key_path:
-      port: 22
-      timeout: 5
-    hosts:
-      - 192.168.1.1
-      - 10.32.100.1
-      # etc.
-atomic_tests:
-  - guid: f7e6ec05-c19e-4a80-a7e7-241027992fdb
-    input_arguments:
-      output_file:
-        value: custom_output.txt
-      input_file:
-        value: custom_input.txt
-    inventories:
-      - windows1
-  - guid: 3ff64f0b-3af2-3866-339d-38d9791407c3
-    input_arguments:
-      second_arg:
-        value: SWAPPPED argument
-    inventories:
-      - windows1
-      - linux1
-  - guid: 32f90516-4bc9-43bd-b18d-2cbe0b7ca9b2
-    inventories:
-      - linux1
-```
+In addition to the ability to pass in parameters with `atomic-operator` you can also pass in a path to a `config_file` that contains all the atomic tests and their potential inputs. You can find more information about the [Configuration File here](atomic-operator-config.md)
 
 ## Package
 

docs/index.md

@@ -24,6 +24,8 @@ Additionally, `atomic-operator` can be used in many other situations like:
 * Can prompt for input arguments but not required
 * Assist with downloading the atomic-red-team repository
 * Can be automated further based on a configuration file
+* A command-line and importable Python package
+* Plus more
 
 ## Getting Started
 
@@ -40,6 +42,7 @@ The next steps will guide you through setting up and running `atomic-operator`.
 * [Get Atomics](atomics.md) Install / clone Atomic Red Team repository
 * [atomic-operator](atomic-operator.md) Understand the options availble in atomic-operator
 * [Running Test on Command Line](running-tests-command-line.md) or [Running Tests within a Script](running-tests-script.md)
+* [Running Tests via Configuration File](atomic-operator-config.md)
 
 ## Installation
 
@@ -119,6 +122,32 @@ You can see additional parameters by running the following command:
 atomic-operator run -- --help
 ```
 
+
+|Parameter Name|Type|Default|Description|
+|--------------|----|-------|-----------|
+|techniques|list|all|One or more defined techniques by attack_technique ID.|
+|test_guids|list|None|One or more Atomic test GUIDs.|
+|atomics_path|str|os.getcwd()|The path of Atomic tests.|
+|check_prereqs|bool|False|Whether or not to check for prereq dependencies (prereq_comand).|
+|get_prereqs|bool|False|Whether or not you want to retrieve prerequisites.|
+|cleanup|bool|False|Whether or not you want to run cleanup command(s).|
+|copy_source_files|bool|True|Whether or not you want to copy any related source (src, bin, etc.) files to a remote host.|
+|command_timeout|int|20|Time duration for each command before timeout.|
+|debug|bool|False|Whether or not you want to output details about tests being ran.|
+|prompt_for_input_args|bool|False|Whether you want to prompt for input arguments for each test.|
+|return_atomics|bool|False|Whether or not you want to return atomics instead of running them.|
+|config_file|str|None|A path to a conifg_file which is used to automate atomic-operator in environments.|
+|hosts|list|None|A list of one or more remote hosts to run a test on.|
+|username|str|None|Username for authentication of remote connections.|
+|password|str|None|Password for authentication of remote connections.|
+|ssh_key_path|str|None|Path to a SSH Key for authentication of remote connections.|
+|private_key_string|str|None|A private SSH Key string used for authentication of remote connections.|
+|verify_ssl|bool|False|Whether or not to verify ssl when connecting over RDP (windows).|
+|ssh_port|int|22|SSH port for authentication of remote connections.|
+|ssh_timeout|int|5|SSH timeout for authentication of remote connections.|
+|**kwargs|dict|None|If additional flags are passed into the run command then we will attempt to match them with defined inputs within Atomic tests and replace their value with the provided value.|
+
+
 You should see a similar output to the following:
 
 ```text

mkdocs.yml

@@ -11,6 +11,7 @@ nav:
         - 'Running Tests on Command Line': 'running-tests-command-line.md'
         - 'Running Tests via Scripts': 'running-tests-script.md'
         - 'Running Tests Remotely On Windows': 'windows-remote.md'
+        - 'Running Tests via Configuration File': 'atomic-operator-config.md'
     - Code Reference:
         'Atomic Operator': 'atomic-operator-ref.md'
         'Data Models': 'models-ref.md'