plugin

Overview ¶

Package plugin provides a client for invoking extractor plugins.

Deputy supports three types of inventory extractors:

1. OSV-SCALIBR extractors (built-in)
2. Deputy custom extractors (built-in, Go)
3. Plugin extractors (external, any language via pluginrpc)

This package handles type 3 - invoking external plugins that implement the ExtractorService defined in api/deputy/plugin/v1/extractor.proto.

Architecture ¶

┌────────────────────────────────────────────────────────────────┐
│                  Deputy (this package)                         │
│                                                                │
│  ┌─────────────┐   ┌──────────────────┐   ┌────────────────┐  │
│  │ NewClient() │──▶│ pluginrpc.Client │──▶│ ExecRunner     │  │
│  └─────────────┘   └──────────────────┘   │ (subprocess)   │  │
│                                           └───────┬────────┘  │
│  ┌─────────────────────────────────────────────────│────────┐ │
│  │ Client Methods                                  │        │ │
│  │  • Info()         - get metadata                │        │ │
│  │  • FileRequired() - check if file matches  ─────┤        │ │
│  │  • Extract()      - extract packages       ─────┤        │ │
│  └─────────────────────────────────────────────────│────────┘ │
└────────────────────────────────────────────────────│──────────┘
                                                     │
                                      ┌──────────────┴──────────┐
                                      │   stdin    │   stdout   │
                                      │  (proto)   │   (proto)  │
                                      ▼            │            │
┌─────────────────────────────────────│────────────│────────────┐
│                    Plugin Process   │            │            │
│                                     │            │            │
│  ┌──────────────────────────────────┴────────────┴─────────┐  │
│  │              pluginrpc.Server                           │  │
│  │  • --protocol flag handling                             │  │
│  │  • --spec flag handling                                 │  │
│  │  • Subcommand routing (info, file-required, extract)    │  │
│  └──────────────────────────┬──────────────────────────────┘  │
│                             │                                  │
│  ┌──────────────────────────▼──────────────────────────────┐  │
│  │              ExtractorService Handler                   │  │
│  │  (implemented via sdk/plugin or custom)                 │  │
│  └─────────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────┘

Plugin Discovery ¶

Plugins are discovered via:

• Configuration: .deputy.yaml plugins.extractors[]
• PATH lookup: executables matching "deputy-extractor-*"
• Runtime registration: client.RegisterExtractor()

Invocation Protocol ¶

Plugins are invoked as subprocesses using pluginrpc:

• Requests are serialized to stdin
• Responses come from stdout
• Trace context is passed via the TraceContext field
• Errors are returned with gRPC-style codes

Trace Context Propagation ¶

┌─────────────────────────────────────────────────────────────┐
│ Deputy Process                                              │
│                                                             │
│  ctx with span ──▶ injectTraceContext() ──▶ "00-abc-def-01" │
│                                                    │        │
└────────────────────────────────────────────────────│────────┘
                                                     │
                                     TraceContext field
                                     in proto request
                                                     │
┌────────────────────────────────────────────────────│────────┐
│ Plugin Process                                     │        │
│                                                    ▼        │
│  extractTraceContext() ──▶ ctx with linked span             │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Example Usage ¶

client, err := plugin.NewClient("deputy-extractor-gemspec")
info, _ := client.Info(ctx)
required, _ := client.FileRequired(ctx, "Gemfile.lock", false, 0644, 1234)
if required {
    packages, _ := client.Extract(ctx, "Gemfile.lock", contents, "/project")
}