Understanding the metadata.yaml File

The metadata.yaml is a crucial element of active scan addons and custom scans in cybersecurity applications. This YAML file functions as a manifest, housing vital metadata that instructs the cybersecurity tool on the specifics of interacting with, handling, and executing each addon or custom scan. It must be attatched to each custom addon created.

The tags are used to automatically load the addons in the proper scenarios, so please ensure each field is carefully populated to guarantee the effective operation of your addon.

Although this metadata file is predominantly employed with Zed Attack Proxy (ZAP) addons at present, its application is not restricted to ZAP. It is also designed to serve other tools, extending its utility across a wide spectrum of custom scans.

This documentation serves as a comprehensive guide for understanding the structure and purpose of each field within the metadata.yaml file.

Name Field

The Name field is designated for the title of the addon. This should be a succinct and clear representation of the addon's functionality, enabling users and developers to quickly understand its purpose at a glance. It is also, used by Prancer as the identifier to load the addon.

Description Field

The Description field provides a more comprehensive explanation of the addon's purpose and functionality. This description should articulate the purpose and primary function of the addon, providing potential users with the necessary context to understand its use.

Charset Field

The Charset field is allocated for defining the character encoding employed by the addon. In the interest of maintaining a universally understood and standardized character set, this field is typically set to UTF-8.

Engine Field

The Engine field specifies the engine that ZAP should utilize to run the addon. This information is critical for ZAP to understand how to process and execute the addon correctly.

Parameters and Secrets Fields

The Parameters and Secrets fields are designed for conveying vital information to the addon. Specifically, the Parameters field is intended for information that should be passed onto the PAC file, while the Secrets field is designated for secret values that should be securely retrieved from a vault.

Type Field

The Type field articulates the category of the addon. This classification allows for more effective organization and execution of addons, enabling ZAP to understand the nature and requirements of each addon. It can be one of the following: - Addon: An addon created to run in ZAP. - Script: A piece of code executed by ZAP. - ZEST: An ZEST instruction set for ZAP. - Standalone: A scan that used seperate tools and doesn't need zap. - Zap: Addons made by ZAP.

Tags Field

The Tags field offers an avenue for supplementary metadata about the addon, providing context in a variety of dimensions:

  • The Cloud tag is utilized to identify the relevant Cloud Service Provider (CSP) associated with the addon.
  • The Compliance tag denotes the specific cybersecurity regulation that the addon complies with or is designed to scan for.
  • The CWEID and MITRE tags are used as cybersecurity vulnerability identifiers, representing the associated Common Weakness Enumeration (CWE) IDs and MITRE ATT&CK IDs respectively.
  • The Os tag provides information on the operating system vulnerabilities that the addon is capable of scanning for.
  • The Programming tag indicates the programming language in which the vulnerability being scanned is written.
  • The Service tag specifies the service through which the connection to test the vulnerability is established.
  • The Type tag within the Tags field delineates the nature of the scan - whether it is a web scan, an API scan, or both.

This guide aims to provide a comprehensive understanding of the metadata.yaml file associated with each OWASP ZAP addon. Proper configuration of this file is pivotal to ensure the correct and efficient operation of each addon. As such, users and developers are encouraged to review and understand each field within the metadata.yaml file thoroughly.

For clarity and better understanding, we provide below a metadata.yaml file with all the possible options supported accepted by Prancer:

Name: Name of the Addon
Description: Description of the Addon
Charset: UTF-8
Engine: [Java, ZEST, ECMAScript, Python]
Parameters:
  ExampleParameter: Parameters that should get passed onto the pac file
Secrets:
  ExampleSecret: Secret values that should be accessed from the vault
Type: [Addon, Script, ZEST, Standalone, Zap]
Tags:
  Cloud: [Azure, AWS, GCP, Onpremise]
  Compliance: [CIS, CSA-CCM, HIPAA, ISO 27001, PCI_DSS, NIST 800, HITRUST, SOC 2, GDPR, Best Practice]
  CWEID: All CWE IDs associated with the addon
  MITRE: All MITRE Att&CK IDs associated with the addon
  Os: [Windows, Linux]
  Programming: Language of the vulnerability being scanned
  Service: [HTTP, FTP, SSH, RDP] 
  Type: [All, Web, OpenAPI, GraphQL, SOAP]