Create your own custom plugins

Artykuł
11/18/2024

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 Security Copilot, 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 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 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 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 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 Security Copilot.