SCA refactor tier 1

[davidjiglesias]

Description

This issue tracks the porting of the Security Compliance Assessment (SCA) module to the new agent architecture. This involves refactoring the existing module to leverage the new agent's capabilities, including persistent state, stateful/stateless messaging, and alignment with the new data model.

Functional Requirements

1. The agent must maintain a persistent internal state.
2. This state must be synchronized to the Indexer via stateful messages.
3. The module must report check result change events via stateless messages.
4. The module must execute scans periodically, with configurable intervals.
5. Existing 4.x policies must be supported (same format).
6. Policy execution behavior must remain consistent with 4.x.
7. The module must support graceful shutdown during scans.
8. Initial policy development for the following operating systems:
   • Amazon Linux 2023
   • Ubuntu 24.04
   • macOS 15 Sequoia
   • Windows 11

Non-Functional Requirements

1. The module must function on Tier 1 supported operating systems.
2. Data stored in the internal state and reported to the server must conform to ECS schema.

Implementation Restrictions

1. The internal state must be implemented using the DBsync library.
2. Policies are assumed to be present on the agent (may be revisited).
3. The module will be developed from scratch:
   • C++ 20 and coroutines.
   • Leverage code from the existing 4.x implementation.

Testing

• Comprehensive integration tests will be developed to ensure the module functions correctly within the new agent framework and across supported operating systems.

Plan

Phase 1: Core SCA Module Development

1. Define Module Interface:
   • Specify the entry points and external interactions of the SCA module.
   • Document the module's configuration parameters.
2. Implement Configuration Parsing:
   • Develop functionality to parse the module's configuration (e.g., YAML, JSON).
   • Handle configuration validation and error reporting.
3. Implement Task Management:
   • Design and implement a system for managing scan tasks (scheduling, execution, cancellation).
   • Integrate with the agent's scheduling mechanisms.
4. Implement Communication Lambdas (Pass-Through):
   • Create communication lambdas for passing messages between the SCA module and other agent components.
   • Ensure proper message routing and handling.
5. Define Output Data Structure (Tentative JSON Example):
   • Create a tentative JSON example representing the output of the SCA module.
   • Include fields for scan results, compliance checks, and metadata.
6. Define ECS Field Mapping (@wazuh-devel-xdrsiem-indexer):
   • Specify the mapping of SCA module fields to the Elastic Common Schema (ECS).
   • Provide this mapping to the Indexer team.
7. Implement YAML Policy Parsing (Translation):
   • Develop functionality to parse existing 4.x YAML policies.
   • Implement requirements checks, variable replacement, and rule parsing.
8. Implement Execution Logic (Translation):
   • Develop logic to execute commands, file/file list checks, directory checks, and process checks.
   • Ensure consistency with 4.x execution behavior.
9. Implement Event Creation and DBsync Usage:
   • Define the database table(s) for storing SCA module state.
   • Implement event creation for check result changes.
   • Integrate with the DBsync library for persistent state management.
   • Implement logic to send statefull and stateless messages.
10. Implement Timeout and Scheduling Logic:
    • Implement timeouts for scan loops and individual checks.
    • Implement configurable scan scheduling.
    • Implement graceful shutdown during scans.
11. Implement Unit Tests:
    • Write unit tests for all new classes and methods.
    • Ensure comprehensive test coverage.

Phase 2: Testing and Validation

12. Implement Integration Tests:
    • Perform manual integration tests to compare policy execution against 4.x.
    • Conduct performance tests using real-case scenario policy files.
    • Graceful shutdown during a scan.
13. Conduct End-to-End (E2E) Test:
    • Develop an E2E test case:
      • Execute an initial scan and visualize the inventory in the dashboard.
      • Execute a subsequent scan and visualize change alerts in the dashboard.
    • Document the results of the E2E test.
14. Document Module Behavior:
    • Document the behavior of all implemented tasks.

Phase 3: Operating System Specific Policies

15. Develop Initial Policies:
    • Develop initial security compliance policies for:
      • Amazon Linux 2023
      • Ubuntu 24.04
      • macOS 15 Sequoia
      • Windows 11

Future Lines (Tier 2)

• Agent-side policy retrieval.
• Policy signing.
• Determine default out-of-the-box policies.
• Management API: SCA endpoints.
• Content Manager extension.
• SCA Provider implementation.
• Introduce a fine-grained scheduled option (like time).