asim-parser-github-pr-packager

name	asim-parser-github-pr-packager
description	Packages the created and validated ASIM schema parser into a GitHub PR for the Azure-Sentinel repository. Use this skill when asked to package a parser into a GitHub PR.

Context

You are responsible for packaging the ASIM parser into a GitHub PR for the Azure-Sentinel repository. This involves creating a PR with the necessary changes to include the new or updated parser in the repository.

Requirements

You will need the following information to package the parser into a GitHub PR:

• Parser names — both the parameter-less parser (ASim<Schema><Vendor><Product>) and the parameterized parser (vim<Schema><Vendor><Product>)
• ASIM schema name that the parser is based on
• KQL queries for both parser files
• Event vendor and event product - These values can be inferred from the parser names.
• Source documentation link provided by the user
• GitHub repository and branch to which the PR should be made (defaults to Azure-Sentinel repository, main branch)

Step 1: Verify prerequisites

Verify the following before proceeding:

1. The Azure-Sentinel repository is cloned locally. If not, ask the user to clone it or provide the local path.
2. The user has a git remote configured with push access. Verify with git remote -v.

Step 2: Create a new branch

Create a new branch based on the target branch (e.g., main) using the naming convention:

asim/<schema>-<vendor>-<product>

For example: asim/networksession-cisco-asa.

Step 3: Add YAML parser files

Create a YAML file for each parser (parameter-less and parameterized) in the directory Parsers/ASim<SchemaName>/Parsers/.

For the schema reference in both parser files, use the exact SchemaTitle and schema-specific aka.ms SchemaLink defined for the schema in .script/tests/asimParsersTest/VerifyASimParserTemplate.py. Do not substitute a Learn documentation URL.

Parameter-less parser: ASim<Schema><Vendor><Product>.yaml

Parser:
  Title: <schema name> ASIM parser for <vendor> <product> <schema name> Events
  Version: '0.1.0'
  LastUpdated: <current date in ISO 8601 format>
Product:
  Name: <vendor> <product>
Normalization:
  Schema: <schema name>
  Version: <schema version>
References:
- Title: ASIM <schema name> Schema
  Link: <schema-specific aka.ms SchemaLink from VerifyASimParserTemplate.py>
- Title: ASIM
  Link: https://aka.ms/AboutASIM
- Title: <vendor> <product> Documentation
  Link: <link to           
  
 

    
     
     
    
     
     
 

Parameterized parser: vim<Schema><Vendor><Product>.yaml

Parser:
  Title: <schema name> ASIM filtering parser for <vendor> <product> <schema name> Events
  Version: '0.1.0'
  LastUpdated: <current date in long date format>
Product:
  Name: <vendor> <product>
Normalization:
  Schema: <schema name>
  Version: <schema version>
References:
- Title: ASIM <schema name> Schema
  Link: <schema-specific aka.ms SchemaLink from VerifyASimParserTemplate.py>
- Title: ASIM
  Link: https://aka.ms/AboutASIM
- Title: <vendor> <product> Documentation
  Link:             
  
 

    
     
     
    
     
     
          
 

Step 4: Add changelog

Create a changelog file in the directory Parsers/ASim<SchemaName>/CHANGELOG/ for both parser files.

<parser name for parameter less parser>.md

# Changelog for <parser name for parameter less parser>

## Version 0.1.0 - <current date in YYYY-MM-DD format>

- (<current date in YYYY-MM-DD format>) Initial creation of the parser
- <other important mappings done in this version that may be relevant for the user to know>

<parser name for parameterized parser>.md

# Changelog for <parser name for parameterized parser>

## Version 0.1.0 - <current date in YYYY-MM-DD format>

- (<current date in YYYY-MM-DD format>) Initial creation of the parser
- <other important mappings done in this version that may be relevant for the user to know>

Step 6: Update unifying parsers

Update the unifying parsers to include the new parsers.

In the directory, Parsers/ASim<SchemaName>/Parsers/, there will be two parsers that include all existing parsers (e.g. ASimAuditEvent.yaml and vimAuditEvent.yaml). Update the following for both yaml files:

• Parser.Version
• Parser.LastUpdated
• Parsers
  • Add the name of the EquivalentBuiltInParser from the created parser.
• ParserQuery
  • Include the function call, including the correct arguments that are required

Step 7: Update unify parsers changelog

Update the unifying parsers changelog files.

In the directory, Parsers/ASim<SchemaName>/CHANGELOG/, there will be two changelogs regarding the unifying parsers(e.g. ASimAuditEvent.md and vimAuditEvent.md). Add a new entry to each changelog file to document the addition of the new parsers.

Step 8. Check if the table is defined in KQL validation tests

In the directory .script/tests/KqlvalidationsTests/CustomTables, check if the source table is defined as one of the files. If there a file that defines the table, the parser is ready to be used in KQL validation tests in GitHub. You can skip this step. If there is no file, then we will need to create a file.

{
  "Name": "<source table name>",
  "Properties": [
    { "name": "<property name>", "type": "<column type>" }, ...
  ]
}

Step 9. Generate a sample data file

Extract the EventVendor and EventProduct from the parameter-less parser. Create a sample data file in the directory Sample Data/ASIM with the following name: {EventVendor}_{EventProduct}_{ASIMSchema}_IngestedLogs.csv

The headers of the CSV file should match the name of the columns from the source table. The source table columns can be derived from Step 8. Generate 10 rows of sample data for the CSV file.

• Make sure that you do not use any information that could be used to identify a real person or organization.
• Make sure to use all the columns that exist in the source table.
• For columns that represent enumerations (dictated by the parser), ensure that the values are representative of the possible options from the parser.

Step 10. Ensure all files are present

For new parsers, ensure that all of the following files are present or have been modified:

• Addition of the new parser files specific to the product being normalized (e.g., ASimAuditEvent{ProductName}.yaml and vimAuditEvent{ProductName}.yaml)
• Addition of the new changelog files for the new parser files (e.g., ASimAuditEvent{ProductName}.md and vimAuditEvent{ProductName}.md)
• Modification of the unifying parsers (e.g., ASimAuditEvent.yaml and imAuditEvent.yaml)
• Modification of the the changelog files for the unifying parsers (e.g., ASimAuditEvent.md and imAuditEvent.md)
• The sample data file (e.g., <EventVendor>_<EventProduct>_<ASIMSchema>_IngestedLogs.csv)

Step 11. Generate ARM templates

Provided that you are in the root directory of the repository (Azure-Sentinel), run the following command to generate the ARM templates: .script\kqlFuncYaml2Arm.ps1 This will generate the necessary ARM templates for the new parsers and update the unifying parsers. There should not be any files deleted after running this script.

Step 11: Commit the changes

Commit all changes with a meaningful commit message, e.g.:

Add ASIM <SchemaName> parser for <Vendor> <Product>