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:
Build a plugin from the list of supported plugins.
Create a YAML or JSON plugin manifest file, which describes metadata about the plugin and how to invoke it.
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 separateGetDeviceById
,GetDeviceByUserId
, andGetDeviceByUserName
- For example, having a single
Copilot for Security supports
Description
andDescriptionForModel
fields.Description
is used in the UX (and for skill selection ifDescriptionForModel
isn't set) andDescriptionForModel
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".