readme

[ahenao4]

Description

read me standardization and updates

Type of change

Please delete options that are not relevant.

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have made corresponding changes to the documentation
• I have added tests that prove my fix is effective or that my feature works

[github-actions]

Wohoo! Your first PR -- thanks for contributing!

[Copilot]

Pull request overview

This PR standardizes and expands the repository README to provide clearer context, installation steps, requirements, and basic usage guidance for the Atomic Caldera plugin.

Changes:

• Replaces the prior short README with expanded sections (overview, limitations, install, requirements, getting started).
• Adds step-by-step installation instructions and dependency notes.
• Adds UI/usage guidance and an additional note about $PathToAtomicsFolder handling.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Typo: "unexisting file" should be "nonexistent file".

Suggested change

- When importing tests from Atomic Red Team, this plugin also catches `$PathToAtomicsFolder` usages pointing to an existing file. It then imports the files as payloads and fix path usages. Note other usages are not handled. If a path with `$PathToAtomicsFolder` points to an existing directory or an unexisting file, we will not process it any further and ingest it "as it is". Examples of such usages below:

- When importing tests from Atomic Red Team, this plugin also catches `$PathToAtomicsFolder` usages pointing to an existing file. It then imports the files as payloads and fix path usages. Note other usages are not handled. If a path with `$PathToAtomicsFolder` points to an existing directory or a nonexistent file, we will not process it any further and ingest it "as it is". Examples of such usages below:

[Copilot]

Grammar: "It then imports the files as payloads and fix path usages" should use consistent verb agreement (e.g., "...and fixes path usages").

Suggested change

- When importing tests from Atomic Red Team, this plugin also catches `$PathToAtomicsFolder` usages pointing to an existing file. It then imports the files as payloads and fix path usages. Note other usages are not handled. If a path with `$PathToAtomicsFolder` points to an existing directory or an unexisting file, we will not process it any further and ingest it "as it is". Examples of such usages below:

- When importing tests from Atomic Red Team, this plugin also catches `$PathToAtomicsFolder` usages pointing to an existing file. It then imports the files as payloads and fixes path usages. Note other usages are not handled. If a path with `$PathToAtomicsFolder` points to an existing directory or an unexisting file, we will not process it any further and ingest it "as it is". Examples of such usages below:

[Copilot]

The example links are prefixed with --, which won’t render as a Markdown list. Use a single - (or number them) so the examples are formatted consistently with the rest of the README.

Suggested change

	-- https://github.com/redcanaryco/atomic-red-team/blob/a956d4640f9186a7bd36d16a63f6d39433af5f1d/atomics/T1022/T1022.yaml#L99
	-- https://github.com/redcanaryco/atomic-red-team/blob/ab0b391ac0d7b18f25cb17adb330309f92fa94e6/atomics/T1056/T1056.yaml#L24
	- https://github.com/redcanaryco/atomic-red-team/blob/a956d4640f9186a7bd36d16a63f6d39433af5f1d/atomics/T1022/T1022.yaml#L99
	- https://github.com/redcanaryco/atomic-red-team/blob/ab0b391ac0d7b18f25cb17adb330309f92fa94e6/atomics/T1056/T1056.yaml#L24

[Copilot]

PR description marks this as a "New feature", but the diff only changes README content. Please update the PR type/checklist to reflect that this is documentation/standardization work (or add the corresponding code changes if a feature is intended).

[Copilot]

Installation instructions reference cloning xenoscr/atomiccaldera, cd atomiccaldera, and enabling atomiccaldera in Caldera, but this repository’s code uses the plugin path/name atomic (e.g., plugins/atomic/... in hook/tests). As written, users following these steps will likely enable the wrong plugin name or end up with the plugin in the wrong folder—please align the README commands and the local.yml plugin entry with the actual plugin directory/name used by this repo.

[Copilot]

The shell commands under the numbered Installation steps aren’t indented as part of the list items, so Markdown renderers will often break/reset the numbering. Consider formatting each step’s commands as an indented code block (or a fenced code block nested under the list item) so they render consistently.

Suggested change

	`cd <path to caldera/plugins>`
	`git clone https://github.com/xenoscr/atomiccaldera.git`
	2. Change directories:
	`cd atomiccaldera`
	3. Install required Python modules:
	`pip install -r requirements.txt`
	4. Clone the Red Canary Atomic Red Team repository:
	`git clone https://github.com/redcanaryco/atomic-red-team.git`
	5. Clone the MITRE CTI repository:
	`git clone https://github.com/mitre/cti.git`
	```sh
	cd <path to caldera/plugins>
	git clone https://github.com/xenoscr/atomiccaldera.git

2. Change directories:

   cd atomiccaldera

3. Install required Python modules:

   pip install -r requirements.txt

4. Clone the Red Canary Atomic Red Team repository:

   git clone https://github.com/redcanaryco/atomic-red-team.git

5. Clone the MITRE CTI repository:

   git clone https://github.com/mitre/cti.git

[Copilot]

README states Python 3.6.8+, but the repo’s CI/tox configuration runs on Python 3.8 (py38). Please update the documented minimum supported Python version to match what’s actually tested/supported (or adjust CI/tox if 3.6 is still intended to be supported).

Suggested change

	1. Python 3.6.8+ with the following libraries installed:
	1. Python 3.8+ with the following libraries installed:

[Copilot]

The Getting Started section uses literal tab characters after the list numbers (e.g., 1. First ...). Tabs can render inconsistently in Markdown; replace them with normal spaces and consider making "Selecting an Ability" a proper sub-heading for readability.

Suggested change

	Selecting an Ability
	To select an ability:
	1. First select a tactic "Select ATT&CK tactic" drop down.
	2. Next select the ability from the "Select ability" drop down.
	After you have selected an ability you can use the left and right arrows to quickly move through the list of available abilities related to the selected tactic.
	Saving an Ability
	If you have made changes to an ability and wish to save them:
	1. Click the "Save Ability" button.
	Saving Variables
	If you have made changes to variables and wish to save them:
	1. Click the "Save Variables" button.
	Export a Single Ability
	If you wish to export the selected ability only to Stockpile:
	1. Click the Export Ability button.
	Export All Abilities
	If you wish to export all of the abilities from Atomic Caldera to Stockpile:
	1. Click the Export All Abilities button.
	Reloading Data (i.e. Start over)
	If you wish to delete everything that has been imported and wish to start over, do so by:
	1. Click the Reload Abilities button
	2. Click the Yes button.
	### Selecting an Ability
	To select an ability:
	1. First select a tactic "Select ATT&CK tactic" drop down.
	2. Next select the ability from the "Select ability" drop down.
	After you have selected an ability you can use the left and right arrows to quickly move through the list of available abilities related to the selected tactic.
	### Saving an Ability
	If you have made changes to an ability and wish to save them:
	1. Click the "Save Ability" button.
	### Saving Variables
	If you have made changes to variables and wish to save them:
	1. Click the "Save Variables" button.
	### Export a Single Ability
	If you wish to export the selected ability only to Stockpile:
	1. Click the Export Ability button.
	### Export All Abilities
	If you wish to export all of the abilities from Atomic Caldera to Stockpile:
	1. Click the Export All Abilities button.
	### Reloading Data (i.e. Start over)
	If you wish to delete everything that has been imported and wish to start over, do so by:
	1. Click the Reload Abilities button
	2. Click the Yes button.