Manage Custom Enrichment - Enrich Assets with CSV File

Manage Custom Enrichment - Enrich assets with CSV file adds or removes Custom Enrichment data contained in a CSV file or SQL Server table to or from assets, using the Custom Enrichment feature.

• Custom Enrichment runs the Enrichment Statement on assets that are the result of the selected query or on assets selected on the relevant assets page.
• In the Run History of this Enforcement Action, under Affected Assets:
  • Successful - The number of assets that the Custom Enrichment rule matched and therefore removed/added the Custom Enrichment data from/to those assets. For Remove Custom Enrichment, includes also those assets that are the result of the selected query but do not have Custom Enrichment even before running the action.
  • Failed or Additional- The number of assets that resulted from the selected query but did not match the Custom Enrichment rule and therefore did not remove/add the Custom Enrichment data from/to those assets.
    • Failed - When the Show assets that did not meet the criteria under 'additional' instead of 'failed' option is disabled (the default).
    • Additional- When the option is enabled.
  Refer to Viewing Enforcement Set Run History to learn more about run results.

📘

Note

To enrich all assets, use a query that returns all assets for each asset module. For example, for the Device module, use the All Devices query, and for the User module, use the All Users query.

Required Fields

These fields must be configured to run the Enforcement Set.

• Action type - Select whether to Add or Remove a custom enrichment to or from assets.

  • When Remove is selected, the custom enrichments are removed from all assets returned by the query selected. To ensure that the enrichment is removed from all assets, select a query that returns all assets for each asset module.

• Select file input method (default: Upload file) - Select one of the following methods to either upload a file or use a file saved in a storage system:

  • Upload file - Upload from your system a CSV file in the Custom Enrichment CSV File format only.
    • Under Select file input, click Upload file to browse for and upload a CSV file in Custom Enrichment CSV File format.
  • Select CSV adapter connection - To use a CSV file from a CSV adapter connection.
    • From the Select adapter connection dropdown, select the connection that contains the CSV file to be used.
    • Prerequisite: Make sure you have configured the relevant CSV file using a CSV adapter connection. Give a name to the connection (connection label) so that you can identify it in the dropdown list. Configure the file name, location and credentials required to access the file using the CSV adapter. These can be SMB, Azure, blob, Amazon S3 bucket, etc.

    📘

    Note

    If you are uploading a file from an online storage location and you want to use this file only for custom enrichment, you must disable the Active connection setting on the CSV adapter connection. In this case, the CSV adapter connection will not fetch new assets.

    

  • Select SQL Server adapter connection - To use an SQL Server table from an SQL Server adapter connection.
    • From the Select adapter connection dropdown, select the connection that contains the SQL Server table to be used.
    • Prerequisite: Make sure you have configured the relevant SQL Server table using an SQL Server adapter connection. Give a name to the connection (connection label) so that you can identify it in the dropdown list. Configure the file name, location, and credentials required to access the file using the SQL Server adapter. These include SQL Server Host, SQL Server Port, SQL Server Database Name, SQL Server Table Name, and Database Type. Is Users Table must be disabled so that Axonius considers the data fetched from the specified table as device data. A table with Software Vulnerabilities data must contain a CVE ID field.

📘

Note

If you are uploading a file from an online storage location and you want to use this file only for custom enrichment, you must disable the Active connection setting on the SQL Server adapter connection (as in the CSV adapter connection screen above). In this case, the SQL Server adapter connection will not fetch new assets.

• Statement - See Custom Enrichment Statement below on how to enter this statement and how it is validated.

Custom Enrichment Statement

Use the Statement box to enter your custom enrichment statement. If you need help writing the statement, learn how to write a Custom Enrichment statement. You can also incorporate custom fields in Custom Enrichment statements.

Using the Syntax Helper

The Syntax Helper assists you to get the correct field names.

1. Under Adapter Fields, select the Adapter and Field Name from the dropdown lists.

2. Next to the displayed Field Name in Statement, click .

3. Paste the copied field name into your statement.

   

📘

Note

• Complex fields are NOT supported in any rule types.

• The Adapter Connection Label field is not supported. Instead, use the Last Fetched From Connection Label field, which holds the value of the existing connection's label.

Statement Validation

As you type your statement, it is automatically validated against a set of rules. This ensures your statement is correctly formatted and compatible with the uploaded CSV file.

The validation process checks for the following:

• It verifies that the necessary columns exist for a given operation. For example, the in_net operator requires a subnet column with content in every row.
• It ensures a consistent number of columns across all rows.
• It checks for invalid characters (e.g., tabs, spaces) in columns that have strict formatting rules, such as the subnet column.
• It confirms that only commas (,) are used as delimiters.
• It verifies that all columns referenced in your statement (assuming it is already written) exist in the uploaded CSV file.

The Validating loading icon appears as you type to indicate the system is checking your statement and the uploaded CSV file for errors. The icon disappears once the validation is complete.

The validation can have one of two outcomes:

• Success - When validation is successful, a green notification appears under the Statement box: Statement was validated successfully.
• Error - If validation fails, a red notification appears under the Statement box. The message provides the location of the error and a description of the issue (e.g., Statement validation failed at [location] [error]). You must correct the error for the statement to be validated again.
  • If the error is related to the CSV file itself, the error message specifies where the problem is located within the file to help you troubleshoot it.
  • If you write your statement before uploading the CSV file, it must be validated again after the file is uploaded to ensure the columns match.

The Save and Run button only becomes active when your statement is successfully validated, your uploaded CSV file is error-free, and all required fields of the Enforcement Action are filled. You can't save or run an action with an invalid statement or an issue in your uploaded CSV file.

Additional Fields

These fields are optional.

• Write enriched values based on aggregated or custom data fields into EC artifacts adapter enrichment field (default: disabled) -

  • Enable this option to write enriched values, which are based on aggregated or custom data fields, into Enrichment: field name under the EC Artifacts adapter. If a field with that name already exists (before enabling this option), this option will work only after you delete the existing field. This option is useful when you want the results of Custom Enrichment to be treated like any other adapter, meaning that the enriched field values in the EC Artifacts adapter are added as values to aggregated fields of the same name. This means that Queries running on aggregated fields treat the enriched value like any other aggregated field value.

  • When this option is disabled, enrichment values, which are based on aggregated or custom data fields, are written to new enrichment fields on the asset in the format Common Enrichment: field name.

• Show assets that did not meet the criteria under 'additional' instead of 'failed' (default: disabled) - Use this option to determine in what category assets that match the Enforcement Set query but do not match the enrichment criteria are displayed in the Run History under Affected Assets:
  • Additional - When this option is enabled.
  • Failed - When this option is disabled.
• Interpret a value with semicolons as a list of values (default: disabled) -
  • Enable this option to interpret a field in the CSV file with embedded semicolons as a multiple value list field with semicolon delimiters.
  • When this option is disabled, semicolons embedded in the field value are considered as characters in the string.

---