This document describes the JSON schema used to define actions in the S4E platform. Every action must conform to this schema before it can be registered, validated, or executed.

Schema Structure

An action definition is a single JSON object containing metadata, parameter declarations, and executor configuration. The platform validates incoming definitions against the canonical schema at registration time and rejects any payload that does not conform.

Required Fields

Optional Fields

Parameter Types

Each entry in the parameters array is an object with the following fields:

Supported Parameter Types

• string -- Free-text value. Supports validation.pattern (regex), validation.min_length, and validation.max_length.
• integer -- Whole number. Supports validation.min and validation.max.
• boolean -- true or false.
• enum -- One value from a fixed set. Requires validation.allowed_values (array of strings).
• secret -- Sensitive value stored encrypted at rest. Never returned in API responses or logs.

Parameter Validation Rules

The platform enforces these rules when an action is invoked:

1. All parameters marked required: true must be present in the request.
2. Values must match the declared type. Type coercion is not performed.
3. String parameters are checked against pattern, min_length, and max_length when specified.
4. Integer parameters are checked against min and max bounds when specified.
5. Enum parameters must match one of the entries in allowed_values.
6. Secret parameters are masked in all audit logs and API output.

Executor Specification

The executor object tells the platform how to run the action logic.

• local -- Runs a script on the S4E worker node. target is the path to a Python or shell script inside the action package.
• remote -- Sends an HTTP request to an external service. target is the full URL.
• opservant -- Delegates execution to an on-premises Opservant agent. target is the registered agent identifier.

Input / Output Mapping

Input mapping allows a playbook to pass runtime variables into action parameters. Output mapping captures results for downstream steps.

"input_mapping": {
  "ip_address": "{{ trigger.alert.source_ip }}",
  "severity": "{{ trigger.alert.severity }}"
},
"output_mapping": {
  "block_result": "result.status",
  "firewall_rule_id": "result.data.rule_id"
}

Variables use the {{ expression }} syntax and are resolved at execution time.

Conditional Execution

The conditions object supports pre-execution checks:

"conditions": {
  "operator": "and",
  "rules": [
    { "field": "{{ trigger.alert.severity }}", "op": "gte", "value": 7 },
    { "field": "{{ trigger.alert.source_ip }}", "op": "not_in", "value": ["10.0.0.0/8"] }
  ]
}

Supported operators: eq, neq, gt, gte, lt, lte, in, not_in, contains, matches.

Schema Versioning

Action schemas follow semantic versioning. The platform stores every version and allows rollback. When a playbook references an action, it pins to a specific MAJOR.MINOR version by default. Patch-level updates are applied automatically.

• Patch (1.0.0 to 1.0.1) -- Bug fixes, no parameter changes.
• Minor (1.0.x to 1.1.0) -- New optional parameters added, backward-compatible.
• Major (1.x.x to 2.0.0) -- Breaking changes to parameters or executor contract.

Complete Example

{
  "id": "a3f8e1b2-7c44-4d2a-9f10-6b8e5d3c1a72",
  "name": "block-ip-on-firewall",
  "version": "1.2.0",
  "type": "containment",
  "description": "Blocks a source IP address on the perimeter firewall via API call.",
  "tags": ["firewall", "containment", "network"],
  "enabled": true,
  "timeout_seconds": 60,
  "retry": {
    "max_attempts": 3,
    "backoff_seconds": 5
  },
  "parameters": [
    {
      "name": "ip_address",
      "label": "IP Address",
      "type": "string",
      "required": true,
      "description": "IPv4 or IPv6 address to block.",
      "validation": {
        "pattern": "^([0-9]{1,3}\\.){3}[0-9]{1,3}$|^([0-9a-fA-F:]+)$"
      }
    },
    {
      "name": "duration_hours",
      "label": "Block Duration (hours)",
      "type": "integer",
      "required": false,
      "default": 24,
      "validation": {
        "min": 1,
        "max": 8760
      }
    },
    {
      "name": "direction",
      "label": "Traffic Direction",
      "type": "enum",
      "required": true,
      "validation": {
        "allowed_values": ["inbound", "outbound", "both"]
      }
    },
    {
      "name": "api_key",
      "label": "Firewall API Key",
      "type": "secret",
      "required": true
    }
  ],
  "executor": {
    "type": "remote",
    "target": "https://firewall.internal/api/v2/rules",
    "method": "POST",
    "headers": {
      "Content-Type": "application/json"
    }
  },
  "input_mapping": {
    "ip_address": "{{ trigger.alert.source_ip }}",
    "direction": "both"
  },
  "output_mapping": {
    "block_status": "result.status",
    "rule_id": "result.data.rule_id"
  },
  "conditions": {
    "operator": "and",
    "rules": [
      { "field": "{{ trigger.alert.severity }}", "op": "gte", "value": 7 }
    ]
  }
}