Extension manifest

The manifest of an extension provides structured metadata about the extension that’s useful for documenting its purpose and data dictionary. Information provided by the active extensions is available for inspection via the /_cerbos/meta endpoint of the Synapse server.

Providing a manifest

Starlark extensions

Implement a function named manifest that returns either a struct or dict structured in the format described in Manifest format.

def manifest():
    return struct(api_version = 1, name = "test", version = "1.0.0", owner = "cerbos.dev/synapse", description = "Test extension")

WASM extensions

Implement a function named manifest that returns a JSON blob structured in the format described in Manifest format.

Go example
//go:wasmexport manifest
func manifest() int32 {
	m := Manifest{
		APIVersion:  1,
		Name:        "test",
		Version:     "1.0.0",
		Owner:       "cerbos.dev/synapse",
		Description: "Test extension",
	}

	if err := pdk.OutputJSON(m); err != nil {
		pdk.SetError(err)
		return 1
	}

	return 0
}

Manifest format

Field Type Description

apiVersion

uint

Manifest API version. Required. Must be set to 1.

name

string

Name of the extension. Required.

version

string

Extension version. Required.

owner

string

Team or person responsible for maintaining the extension.

description

string

High-level description of the extension’s purpose.

fieldMappings

list of FieldMapping

Describe how the extension maps data to PDP requests.
FieldMapping
Field Type Description

targets

map of field path to target type

Describe the paths of PDP request/responses being modified. The key is the JSON path of the field such as resource.kind and the value is the target. Valid values for target are:

  • TARGET_CHECK_RESOURCES_REQUEST

  • TARGET_CHECK_RESOURCES_RESPONSE

  • TARGET_PLAN_RESOURCES_REQUEST

  • TARGET_PLAN_RESOURCES_RESPONSE

  • TARGET_AUTHZEN_EVALUATION_REQUEST

  • TARGET_AUTHZEN_EVALUATION_RESPONSE

  • TARGET_AUTHZEN_EVALUATION_BATCH_REQUEST

  • TARGET_AUTHZEN_EVALUATION_BATCH_RESPONSE

description

string

Description of this enrichment.

operation

enum

The type of enrichment such as adding a value, overwriting an existing value and so on. Valid values are:

  • OPERATION_ADD

  • OPERATION_REMOVE

  • OPERATION_OVERWRITE

  • OPERATION_APPEND

value

Value

Describe how the value is computed. Values can be static or dynamic. See below for the schema of this field.

jsonSchema

object

A JSON schema snippet describing this field.

metadata

object

Key-value pairs of additional metadata you want to attach to this enrichment description.
Value
Field Type Description

staticValue

any

The static value being assigned to this field. Mutually exclusive with computedValue.

computedValue

ComputedValue

Describes a value computed dyanmically from the request. Mutually exclusive with staticValue. See below for schema.
ComputedValue
Field Type Description

description

string

Describe the computation.

sources

string list

Sources of data used for the computation.

Example

Example manifest from the built-in Aperture extension
{
  "apiVersion": "1",
  "name": "aperture",
  "version": "dev",
  "owner": "cerbos.dev/synapse",
  "description": "Integration point for Aperture by Tailscale",
  "fieldMappings": [
    {
      "targets": {
        "requestId": "TARGET_CHECK_RESOURCES_REQUEST"
      },
      "description": "Request ID from Aperture metadata",
      "operation": "OPERATION_ADD",
      "value": {
        "computedValue": {
          "sources": [
            "metadata.request_id"
          ]
        }
      },
      "jsonSchema": {
        "type": "string"
      }
    },
    {
      "targets": {
        "principal.id": "TARGET_CHECK_RESOURCES_REQUEST"
      },
      "description": "Principal ID from Aperture metadata",
      "operation": "OPERATION_ADD",
      "value": {
        "computedValue": {
          "sources": [
            "metadata.login_name"
          ]
        }
      },
      "jsonSchema": {
        "type": "string"
      }
    },
    {
      "targets": {
        "principal.roles": "TARGET_CHECK_RESOURCES_REQUEST"
      },
      "description": "Principal roles (hardcoded)",
      "operation": "OPERATION_ADD",
      "value": {
        "staticValue": [
          "user"
        ]
      },
      "jsonSchema": {
        "items": {
          "type": "string"
        },
        "type": "array"
      }
    },
    {
      "targets": {
        "principal.attr.stable_node_id": "TARGET_CHECK_RESOURCES_REQUEST"
      },
      "description": "Stable node ID from Aperture metadata",
      "operation": "OPERATION_ADD",
      "value": {
        "computedValue": {
          "sources": [
            "metadata.stable_node_id"
          ]
        }
      },
      "jsonSchema": {
        "type": "string"
      }
    },
    {
      "targets": {
        "principal.attr.tailnet_name": "TARGET_CHECK_RESOURCES_REQUEST"
      },
      "description": "Tailenet name from Aperture metadata",
      "operation": "OPERATION_ADD",
      "value": {
        "computedValue": {
          "sources": [
            "metadata.tailnet_name"
          ]
        }
      },
      "jsonSchema": {
        "type": "string"
      }
    },
    {
      "targets": {
        "principal.attr.user_agent": "TARGET_CHECK_RESOURCES_REQUEST"
      },
      "description": "User agent from Aperture metadata",
      "operation": "OPERATION_ADD",
      "value": {
        "computedValue": {
          "sources": [
            "metadata.user_agent"
          ]
        }
      },
      "jsonSchema": {
        "type": "string"
      }
    },
    {
      "targets": {
        "resource.id": "TARGET_CHECK_RESOURCES_REQUEST"
      },
      "description": "Resource ID",
      "operation": "OPERATION_ADD",
      "value": {
        "staticValue": "aperture_hook"
      },
      "jsonSchema": {
        "type": "string"
      }
    },
    {
      "targets": {
        "resource.kind": "TARGET_CHECK_RESOURCES_REQUEST"
      },
      "description": "Resource Kind",
      "operation": "OPERATION_ADD",
      "value": {
        "staticValue": "aperture_hook"
      },
      "jsonSchema": {
        "type": "string"
      }
    },
    {
      "targets": {
        "resource.policyVersion": "TARGET_CHECK_RESOURCES_REQUEST"
      },
      "description": "Resource policy version",
      "operation": "OPERATION_ADD",
      "value": {
        "staticValue": "production"
      },
      "jsonSchema": {
        "type": "string"
      }
    },
    {
      "targets": {
        "resource.scope": "TARGET_CHECK_RESOURCES_REQUEST"
      },
      "description": "Resource scope",
      "operation": "OPERATION_ADD",
      "value": {
        "staticValue": ""
      },
      "jsonSchema": {
        "type": "string"
      }
    },
    {
      "targets": {
        "resource.attr": "TARGET_CHECK_RESOURCES_REQUEST"
      },
      "description": "Resource attributes",
      "operation": "OPERATION_ADD",
      "value": {
        "computedValue": {
          "sources": [
            "metadata"
          ]
        }
      },
      "jsonSchema": {
        "type": "object"
      }
    },
    {
      "targets": {
        "actions": "TARGET_CHECK_RESOURCES_REQUEST"
      },
      "description": "Resource actions",
      "operation": "OPERATION_ADD",
      "value": {
        "staticValue": [
          "hook_event"
        ]
      },
      "jsonSchema": {
        "items": {
          "type": "string"
        },
        "type": "array"
      }
    }
  ]
}