Share via

Create your own custom plugins

You can extend Security Copilot's capabilities by creating your own custom plugins. The platform supports a flexbile framework to build plugins that can be used to perform specialized tasks that fit your workflow requirements.

Creating new plugins

Depending on how your admins configure Security Copilot, you may be able to create new plugins by taking the following steps:

  1. Build a plugin from the list of supported plugins.

  2. Create a YAML or JSON plugin manifest file, which describes metadata about the plugin and how to invoke it.

  3. Publish the plugin manifest to Security Copilot.

Plugin requirements

Every Security Copilot plugin requires a YAML or JSON formatted manifest file (for example: plugin.yaml or plugin.json) which describes metadata about the skill set and how to invoke the skills.

A manifest consists of two required top level keys, Descriptor and SkillGroups, each with subkey or value pairs, and required/optional fields depending on the skill format.

For information see, Agent manifest.

Differences between OpenAI and Security Copilot manifests

OpenAI plugins built by following the ChatGPT Plugin documentation typically use a different manifest format than the Security Copilot manifest format. Security Copilot supports both formats.

The OpenAI plugin manifest when uploaded, is translated to the Security Copilot manifest.

Note

Mapping details especially around restrictions in notes can change in the future. Currently, the platform only supports plugins in OpenAPI versions 3.0 or 3.0.1.

Plugin field mapping

Plugin field Type Descriptor Field Required Notes
schema_version string No It's the OpenAI manifest schema version, for example 'v1'. Currently not used.
name_for_model string Name Yes Restricted to length of 100 chars. Internal name of the skillset. Doesn't allow / \ ? #.
name_for_human string DisplayName Yes Human-readable name of the plugin. Restricted to length of 40 chars.
description_for_model string Description Yes Restricted to length of 16,000 chars. Internal description for use with LLM.
description_for_human string DescriptionDisplay Yes Human-readable description of the Plugin. Restricted to length of 200 chars.
logo_url string Icon Recommended URL used to fetch the main icon for the Plugin.
contact_email string No Email contact for plugin. Currently not used.
legal_info_url string No Link for plugin information. Currently not used.
api object See Plugin API section for object structure Yes
auth object Yes authorization_type is restricted to bearer. Details to follow on support for different auth type like none, oauth, api_key, aad, aad_delegated.

Plugin (API field)

Object structure for api field

Field Type Description Required
type string The only supported type currently is openapi. Yes
url string Link to your OpenAPI specification file Yes

Plugin authoring guidance

There are many considerations around plugin authoring. This document is meant to capture some of the guidelines and best practices for writing plugins for Security Copilot.

Note

A "skill collision" occurs when Security Copilot doesn't accurately distinguish between two different skills.

  • Instead of having multiple skills that return the same type of response but only differ based on inputs; define skills, which take multiple inputs and then internally figure out how to get the data.

    • For example, having a single GetDevices skill which takes either device ID, user ID or user name instead of separate GetDeviceById, GetDeviceByUserId, and GetDeviceByUserName

  • Security Copilot supports Description and DescriptionForModel fields. Description is used in the UX (and for skill selection if DescriptionForModel isn't set) and DescriptionForModel is only used for skill selection.

    • For example, say we have a skill GetSslCertsByHostname, with a description of "Returns the SSL certificates associated with a hostname". A detailed descriptionForModel could be "Retrieves SSL certificates (also known as TLS certificates) for a DNS hostname or domain name. Returns a list of SSL certificates along with certificate details such as issuer, subject, serial number, sha1, and dates".

  • Skill descriptions should be verbose and phrased for someone who is reasonably knowledgeable, but may not be an expert in your problem domain. It should describe not just what the skill does, but also why someone would want to use it.

    • For example, a good description is "Gets reputation information for an IP address. Enables users to determine if an IP address is risky".  

See also