Create your own custom plugins

Important

Some information in this article relates to a prereleased product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Tip

If you need help with non-Microsoft plugins, refer to their documentation and technical support.

Creating new plugins

Depending on how your admins configure Copilot for Security, 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 Copilot for Security.

Plugin requirements

Every Copilot for Security 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 sub-key or value pairs, and required/optional fields depending on the skill format.

For information on OpenAI plugins, see Getting started.

Descriptor field summary

Field Type Description Required
Name string Internal name of the Plugin. Doesn't allow / \ ? # @. Yes
DisplayName string Human-readable name of the Plugin. Recommended
Description string Human-readable description of the Plugin. Yes
DescriptionDisplay string Alternate human-readable description of the Plugin if Description isn't specified. No
Category string Note: This value currently is forced to Plugin during the custom plugin upload process. No
Prerequisites string No
Icon string URL used to fetch the main icon for the Skillset. Recommended

SkillGroups field summary

Consists of a list of skill groups including Format, Settings, and Skills.

Field Type Description Required
Format string See Format section for available options. Yes
Settings object See Settings section for object structure. Yes, for formats: API, DOTNET, CONTAINER
Skills object See Skills section for object structure. Yes, for formats: GPT, DOTNET, KQL, LogicApp

Format (SkillGroups field)

Options for Format field:

API
GPT
KQL

Settings (SkillGroups field)

Object structure for Settings field.

Field Type Description Required
OpenApiSpecUrl string URL for public OpenAPI spec. Yes
EndpointUrl string URL for public endpoint. No

Skills (SkillGroups field)

Object structure for Skills field.

Field Type Description Required
Description string Human-readable description for this skill. Recommended
DescriptionForModel string Detailed description of the skill used for skill selection No
Inputs object List of Name, Description, Required, and DefaultValue (optional) objects for user input to the skill.
Settings object Custom settings based on the skill Format.

Differences between OpenAI and Copilot for Security manifests

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

The OpenAI plugin manifest when uploaded, is translated to the Copilot for Security 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 OpenAPI specification document of the API. 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 Copilot for Security.

Note

A "skill collision" occurs when Copilot for Security does not 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
  • Copilot for Security 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