Azure-Sentinel/.script/ReadMe.md

How to add new PR validation

At the time of submitting your Pull Request, automatic GitHub validations using Azure Pipelines is enabled on this repository for basic syntactical checks of the contributions. You can add custom tests as needed based on your scenario following this guidance.

What is Azure Pipelines

Azure Pipelines is a cloud service that you can use to automatically build and test your code project and make it available to other users. It works with just about any language or project type.

How to add new PR validation:

1. Install the following extensions, if you use VS Code editor:

   • Azure Pipelines
   • Yaml

2. Run "npm install" cmd, in order to install the libraries used in this project.
   The libraries are defined in package.json

3. Create an Azure Pipeline job for the new validation.
   Add new yaml file under .azure-pipelines folder, see example in yamlFileValidator.yaml file (note - the script code should be added on another file for clearer code, see in step #5).

   • Add scripts those are relevant to the specific folder under one yaml file in the same job. The validation infrastructure and the examples are in TypeScript, but you can use other languages if you prefer
   • Azure Pipelines work with many languages such as Python, Java,JavaScript, PHP, Ruby, C#, C++, and Go. Refer to Azure Pipelines documentation for further information on this.

4. Add the new job to azure-pipelines.yml file as a new template under jobs property

5. Create script file for the new validation. The job from step #3 has reference to this file. See instructions in How to add script validation section.
   A step is a failure if it either explicitly reports failure (using a ##vso command) or ends the script with a non-zero exit code

6. Test the new validation. See instruction in How to test the new validation section

How to add scipt validation

Note: All script logs are public and display in DevOps pipeline.
By default, the logs color is white. In case you want another color you can use logging commands

1. Create script file under .script folder

2. In case you use TypeScript language, you can use the infrastructure script. See example in yamlFileValidator.ts:

   • Create an async validation function that gets the file path.
     In case the validation pass the function returns success, otherwise throws an exception (don't return an error, this will handle by the infrastructure).
   • Create CheckOptions object with 3 properties:
     • onCheckFile: the validation validetion function that will run on each file (from step one)
     • onExecError: error behavior in case that the file validation failed
     • onFinalFailed: error behavior at the end of the validation, execute in case one of the validation failed
   • Call runCheckOverChangedFiles with properties:
     • checkOptions: the object you create in the earlier step 2
     • fileKinds: file kind filter, there are 3 kinds- "Added", "Modified", "Deleted"
     • fileTypeSuffixes : file type filter, example: ["yaml", "yml"]
     • filePathFolderPreffixes: folder path filter, example: ["Detections"]
   • Run prettier command to fix type script files format.
     • install "npm install -g prettier" if needed
     • Run cmd: prettier --write --print-width 200 ".script/**/*.ts"

How to test the new validation

1. In case the language script is TypeScript, check the new validation function by local tests. Since most of the code are the same, these tests will help you validate your changes before it gets merged to master.
   See example in yamlFileValidatorTest folder.

   • Create new folder under .script/test. folder name format: TestedFileName+Test
   • Create tests file. File name format: TestedFileName.test.ts
   • Run the test by execute from cmd "npm test".
     Since it is run locally you will see "Azure DevOps CI for a Pull Request wasn't found. If issue persists - please open an issue" message. You can ignore it.
   • In order to debug the test file, select "Mocha Current File" option in VSCode

2. After the code is merged to master, create a Draft PR to test the new validation. Check both options, pass and failed.

   • (Draft PR marked as "Work in Progress" and cannot be merged, more info here).
   • Remember to delete the draft PR.