[Docs] Update docs based on alpha release (#5)

Author: Mikaayenson

docs/about.md

@@ -9,6 +9,8 @@ This guide was authored and is maintained by:
 
 This guide is meant to enable the implementation of detections as code in a generic manner, through the application of its use on Elastic detection rules (SIEM). We will continue to maintain and improve this guide, especially in the early stages of the new code and adoption, with intent of this eventually stabilizing.
 
+If you have any feedback or questions along the way, the best place to reach us is in the public slack channel for [security-rules-dac](https://elasticstack.slack.com/archives/C06TE19EP09).
+
 ## Licensing and Use
 
 See the LICENSE file for licensing information. This guide is provided as-is and is not officially supported by Elastic. It is intended to be a community-driven project, and we welcome contributions and feedback.

docs/core_component_managing_detection_rules_in_a_vcs.md

@@ -56,11 +56,53 @@ Reference the [Unit Tests](./internals_of_the_detection_rules_repo.md#unit-tests
 
 ### Custom Unit Tests
 
-WIP
+Custom unit tests enable teams to create and execute their own test suites tailored to their specific detection rules and operational requirements. By developing custom tests, teams can extend the validation beyond the pre-configured tests provided in the detection-rules repository. This approach is crucial for organizations that have unique rule logic or complex detection scenarios not covered by the standard test suite.
+
+##### Sub-Component: Custom Test Development
+
+Developing custom unit tests typically involves leveraging Python’s `pytest` framework, which is already installed as a python dependency into the Elastic detection-rules repo. Teams can create a separate directory for custom tests to ensure they are isolated from the general test suite, which allows for more controlled execution and easier maintenance.
+
+###### Option 1: Isolated Test Environment
+
+| Pros | Cons |
+|------|------|
+| - Ensures that custom tests do not interfere with general repository tests.</br> - Allows for targeted testing of specific rule logic or configurations unique to the team’s environment. | - Requires additional setup to integrate with existing CI/CD pipelines.</br> - May require duplication of some setup code or fixtures used in the main test suite.|
+
+**Steps:**
+
+1. Create a new directory within the forked detection-rules repository specifically for custom tests (e.g., `custom_tests/`).
+2. Develop custom test scripts using `pytest`, focusing on the specific aspects of detection rules that are critical to your operational context.
+3. Configure your CI/CD pipeline to include running these custom tests as part of the rule validation process.
+4. Ensure that test results are reviewed and acted upon as part of the pull request review process.
+
+###### Option 2: Integrated Test Suite
+
+Integrate custom unit tests directly into the existing `pytest` configuration, using tags or markers to distinguish them from standard tests. This method leverages the full power of the existing testing infrastructure without needing significant modifications to the CI/CD setup.
 
 | Pros | Cons |
-| - | - |
-|||
+|------|------|
+| - Leverages existing testing tools and configurations.</br> - Simplifies the CI/CD pipeline by using a single test command. | - Requires careful management of test markers to avoid executing unwanted tests.</br> - Potential for confusion or conflicts with upstream test cases if not managed properly.|
+
+**Steps:**
+
+1. Use `pytest` markers to tag custom tests, e.g., `@pytest.mark.custom`.
+2. Modify the CI/CD test execution command to selectively run tests based on tags, e.g., `pytest -m custom`.
+3. Maintain a clear documentation and naming convention for custom tests to ensure they are easily identifiable.
+4. Regularly review and update the custom tests to align with any changes in detection rule structures or the underlying platform.
+
+### Integration with CI/CD
+
+Ensure that the integration of custom unit tests into the CI/CD pipeline is seamless and provides real-time feedback on the rule validation status. This integration is vital for maintaining the agility and responsiveness of the security operations team, enabling rapid deployment of validated and tested detection rules.
+
+|Pros|Cons|
+|-|-|
+| - Immediate feedback on rule validation enhances the agility of rule deployment.</br> - Ensures that only thoroughly tested and validated rules are deployed, reducing the risk of false positives or ineffective detections. | - Requires continuous maintenance to align the test suite with evolving detection rules and threat landscapes.</br> - Initial setup and integration can be complex, requiring expertise in both security and CI/CD technologies.|
+
+**Steps:**
+
+1. Configure the CI/CD pipeline to automatically run custom unit tests on every commit to a designated branch or on pull request creation.
+2. Set up notifications or integration with development tools to alert developers to test failures or issues detected during CI/CD.
+3. Regularly review the test coverage and effectiveness, adjusting the test suite as necessary to cover new threat scenarios or rule changes.
 
 ### Schemas and Data Structures
 

docs/core_component_syncing_rules_and_data_from_elastic_security_to_vcs.md

@@ -48,13 +48,36 @@ This approach involves creating a CI/CD workflow, such as a GitHub Action, that
 1. Script the API calls to Elastic Security for rule extraction.
 
 ```bash
-<Example CLI wrapping the API>
+# Export Rules from Elastic Security
+python -m detection_rules kibana export-rules -d test-export-rules --skip-errors
+
+█▀▀▄ ▄▄▄ ▄▄▄ ▄▄▄ ▄▄▄ ▄▄▄ ▄▄▄ ▄▄▄ ▄   ▄      █▀▀▄ ▄  ▄ ▄   ▄▄▄ ▄▄▄
+█  █ █▄▄  █  █▄▄ █    █   █  █ █ █▀▄ █      █▄▄▀ █  █ █   █▄▄ █▄▄
+█▄▄▀ █▄▄  █  █▄▄ █▄▄  █  ▄█▄ █▄█ █ ▀▄█      █ ▀▄ █▄▄█ █▄▄ █▄▄ ▄▄█
+
+DEBUG MODE ENABLED
+- skipping Stolen Credentials Used to Login to Okta Account After MFA Reset - ValidationError
+- skipping First Occurrence of Okta User Session Started via Proxy - ValidationError
+- skipping ESQL test: cmd child of Explorer - ValidationError
+- skipping Potential Persistence Through Run Control Detected - ValidationError
+- skipping First Time Seen AWS Secret Value Accessed in Secrets Manager - ValidationError
+- skipping Potential Shadow File Read via Command Line Utilities - ValidationError
+- skipping Abnormal Process ID or Lock File Created - ValidationError
+- skipping New service installed in last 24 hours - ValidationError
+- skipping Scheduled Task or Driver added - KqlParseError
+- skipping Scheduled Task or Driver removed - KqlParseError
+- skipping name - ValidationError
+33 rules exported
+22 rules converted
+22 saved to test-export-rules
+11 errors saved to test-export-rules/_errors.txt
 ```
 
 3. Format and commit the extracted rules into VCS, optionally creating a PR for review.
 
 ```bash
-<Indicate the step in the workflow that does this.>
+# Import Rules into Detection Rules
+python -m detection_rules import-rules-to-repo ...
 ```
 
 ### Option 2: Cron Scheduling Pull