Agent Configuration (agent_config.yaml)

The agent_config.yaml file is a crucial component of the ShellSweepX system, providing configuration details for remote agents. This YAML file defines scanning parameters, file types to analyze, and specific rules for entropy-based detection.

File Structure and Purpose

1. directory_paths:

   • Lists directories to be scanned by the agents.
   • Focuses on critical areas like Exchange Server and IIS web roots.

2. exclude_paths:

   • Specifies directories to be excluded from scanning.
   • Helps avoid false positives and unnecessary processing.

3. file_extensions:

   • Defines file types to be analyzed.
   • Each file type has associated entropy thresholds for detection.

4. ignore_hashes:

   • Lists SHA256 hashes of files to be ignored during scans.
   • Useful for whitelisting known good files.

Entropy-Based Detection

The file_extensions section uses entropy thresholds for initial webshell detection:

• operation: gt (greater than) or lt (less than)
• value: The entropy threshold

For example, for .php files:

.php:
operation: gt
value: 4.23015141285636

This means a PHP file with entropy greater than 4.23 is flagged for further analysis.

Technical Details

1. YAML Format:

   • Uses YAML for human-readability and easy parsing.
   • Allows for structured data representation.

2. Delivery Mechanism:

   • The configuration is served via the /api/agent_config endpoint in the main application.
   • Agents periodically fetch this configuration to update their scanning parameters.

3. Dynamic Updates:

   • The configuration can be updated through the Settings page in the web interface.
   • Changes are immediately reflected in the API response, allowing for real-time agent configuration updates.

4. Parsing in Agents:

   • Agents use YAML parsing libraries (e.g., PyYAML for Python agents) to read this configuration.
   • The parsed data structures guide the scanning and analysis process on the agent side.

5. Flexibility:

   • The YAML structure allows for easy addition of new parameters or rules.
   • Administrators can fine-tune the scanning process without modifying agent code.

6. Security Considerations:

   • The configuration should be transmitted securely (e.g., over HTTPS).
   • Access to the configuration endpoint should be restricted to authenticated agents.

7. Version Control:

   • It's recommended to version control this file to track changes over time.
   • Consider implementing a version field in the YAML for compatibility checks.

8. Performance Impact:

   • The exclude_paths helps optimize performance by avoiding unnecessary scans.
   • Entropy thresholds allow for quick initial filtering before more intensive analysis.

Usage in the ShellSweepX System

1. Agent Initialization:

   • Agents fetch this configuration upon startup.
   • Regular updates ensure agents always use the latest scanning parameters.

2. Scan Process:

   • Agents use directory_paths and exclude_paths to determine scan targets.
   • File extensions and entropy thresholds guide the initial detection process.
   • ignore_hashes are checked to skip known safe files.

3. Reporting:

   • Agents use this configuration to determine which files to report back to the central server for further analysis.

By centralizing this configuration, ShellSweepX ensures consistent behavior across all deployed agents while allowing for flexible and dynamic updates to the scanning process.