Understanding the metadata.yaml File
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
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 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 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 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
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 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 offers an avenue for supplementary metadata about the addon, providing context in a variety of dimensions:
Cloudtag is utilized to identify the relevant Cloud Service Provider (CSP) associated with the addon.
Compliancetag denotes the specific cybersecurity regulation that the addon complies with or is designed to scan for.
MITREtags are used as cybersecurity vulnerability identifiers, representing the associated Common Weakness Enumeration (CWE) IDs and MITRE ATT&CK IDs respectively.
Ostag provides information on the operating system vulnerabilities that the addon is capable of scanning for.
Programmingtag indicates the programming language in which the vulnerability being scanned is written.
Servicetag specifies the service through which the connection to test the vulnerability is established.
Typetag within the
Tagsfield 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]