External module protocol

External modules are executable processes. Xila is the JSON-RPC 2.0 client and starts a module on first use. stdin and stdout are reserved for protocol frames; diagnostics go to stderr.

Manifest

Place xila-module.yaml beside the executable:

id: example-analyzer
kind: analyzer
version: 1.0.0
schema: xila/v1
description: Checks studio-specific configuration
consumes: [text, config-file]
produces: [finding]
runtime:
  type: exec
  command: [./example-analyzer]
  timeout: 30s
  env: {}
permissions:
  network: false
  filesystem: read-only-input
  secrets: []
  exec: false

kind is extractor, analyzer, prober, detector or reporter. A relative command resolves from the manifest directory. Xila discovers manifests no more than three directories below each --modules root. Unknown manifest fields and schema mismatches fail closed.

Framing

Each UTF-8 JSON message uses Language Server Protocol framing:

Content-Length: 61\r\n
\r\n
{"jsonrpc":"2.0","id":1,"method":"supports","params":{}}

Content-Length is the byte length of the JSON body. Frames over 64 MiB are rejected. One request is active per process; IDs are unsigned integers.

Lifecycle and methods

1. initialize includes host name, host version and xila/v1; return the module manifest. The returned ID and schema must match the file manifest.
2. Kind-specific requests follow:
   • extractor: supports, then extract; stream components with component notifications before the final extract response;
   • analyzer: accepts, then analyze;
   • prober: probe;
   • detector: evaluate;
   • reporter: report.
3. The host sends shutdown, then the exit notification when closing.

Components cross the process boundary with their content base64 encoded. Findings, runs, signals and assessments use the public xila/v1 JSON forms. Errors use standard JSON-RPC codes plus -32000 module panic, -32001 schema mismatch and -32002 unsupported method.

Go SDK

Implement the relevant interface from core/module, then serve it:

package main

import (
    "log"
    modulesdk "github.com/xilasec/xila/sdk/module-go"
)

func main() {
    if err := modulesdk.Serve(analyzer{}); err != nil {
        log.Fatal(err) // stderr only
    }
}

modulesdk.Serve handles framing, initialization, dispatch, component encoding and panic conversion. Run with xila scan BUILD --modules ./modules.

Permissions

The manifest drives host policy: modules declaring network access are skipped unless the user passes --allow-network, and modules requesting unavailable named secrets are skipped. External processes receive a minimal environment and the artifact payloads selected by the host.

On a developer workstation this is not an OS security sandbox. A dishonest executable could use undeclared filesystem, process or network capabilities. Install external modules only from trusted publishers. Hosted workers must add an operating-system or container sandbox around the same protocol.