cuboid 0.3.6 → 0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 171b5e2f29598954e7bb187061cfbc5ff520b05ba87fa9eee1f4d37e0f1061e3
-  data.tar.gz: cd3f65b26beb8745afa941902ed6d3783d7792139081285e4df6a1795034c86e
+  metadata.gz: 51212d2d1adc9ffb33f4838212d9bbddcb88466a12e8e1b5522a2baff6b233f0
+  data.tar.gz: e4721af5a566266882fea5320129f58d01c667a03956d79300a3b3a3b652edc1
 SHA512:
-  metadata.gz: f5bb4086c573b41372d79faae0c7b243d337333dc1bfa5ae326eca53ddd47f2e4a64aef5b5751362c9b9754ce8ef181cb7a665db7ecb88c3360100c4cc78ad22
-  data.tar.gz: 20a8d4d77b283d655a7d0a122b4ad1b71b7b6b4461acdea2f35d458f64962e564a9d472ad82ad4d147a5c31550b70ad3a86120e07393c95045c598597323c1ad
+  metadata.gz: c2cec6fd1a808c0fc1473a61a7f93a0e3ed7a974562df6c44b55e4e450461cef29320d82a252de344eb1d21ceec94f6e4e8bd7bfd7f7301ccb05f15561c3255e
+  data.tar.gz: c7f15a7207fa170a0874c9931a75533bb6ba37dda9a0b2a0b2946a019ea90f16258b5051ab523fbc5ca59795c0f948ff18fac1434c55ca7ae7b860198576b94e

data/README.md

@@ -62,6 +62,17 @@ framework:
   * `instance_service_for( Symbol, Class )` -- Adds a custom _**Instance**_ RPC API.
   * `rest_service_for( Symbol, Module )` -- Hooks-up to the _**REST**_ service to provide a custom REST API.
   * `agent_service_for( Symbol, Class )` -- Hooks-up to the _**Agent**_ to provide a custom RPC API.
+  * `mcp_service_for( Symbol, Module )` -- Registers an _**MCP**_ service module
+    (its `tools` / `prompts` / `resources` / `read_resource` are exposed at
+    `/mcp` and routed per-instance via `instance_id`).
+  * `mcp_app_tool( MCP::Tool )` -- Ships an app-level _**MCP**_ tool at the
+    top-level `/mcp` endpoint, alongside `list_instances` / `spawn_instance`
+    / `kill_instance` -- no `instance_id` required (catalogue / metadata
+    tools the client may want to consult before spawning anything).
+  * `mcp_authenticate_with { |bearer_token| ... }` -- Bearer-token
+    validator for the _**MCP**_ transport; block returns a truthy
+    principal on success, `nil` to reject. Without one the server
+    accepts unauthenticated traffic.
   * `serialize_with( Module )` -- A serializer to be used for:
     * `#options`
     * `Report#data`
@@ -163,6 +174,76 @@ management for the rest of the entities.
 Each _**Application**_ can extend upon this and expose an API via its _**REST**_ 
 service's interface.
 
+### MCP
+
+An [Model Context Protocol][mcp] server is also available, allowing AI clients
+(Claude Desktop / Code, Cursor, Continue, anything that speaks MCP) to drive
+_**Applications**_ end-to-end over a single Streamable-HTTP endpoint
+(`POST /mcp` for request/response, `GET /mcp` for the server-initiated SSE
+notifications channel).
+
+Spin up the MCP server with:
+
+```ruby
+MyApp.spawn(:mcp, ssl: { ... })
+```
+
+[mcp]: https://modelcontextprotocol.io/
+
+#### Tools
+
+Three tools ship at the top-level endpoint by default
+(`Cuboid::MCP::CoreTools`):
+
+| Tool             | Required        | Returns                       |
+|------------------|-----------------|-------------------------------|
+| `list_instances` | --              | `{ instances: { <id>: { url } } }` |
+| `spawn_instance` | --              | `{ instance_id, url, live: { notification_method } }` |
+| `kill_instance`  | `instance_id`   | `{ killed: <id> }`            |
+
+Per-service tools (registered via `mcp_service_for`) take an `instance_id`
+argument and are dispatched to the matching engine instance. App-level
+catalogue tools (registered via `mcp_app_tool`) live at the top-level
+endpoint without an `instance_id` requirement.
+
+#### Live channel
+
+Every `spawn_instance` attaches the calling MCP session to a live
+notification stream — every interesting state change inside the engine
+arrives as a JSON-RPC `notifications/<brand>/live` notification on the SSE
+half of the transport, where `<brand>` is derived from the umbrella's
+`shortname` (falling back to `cuboid` for bare-cuboid builds). The spawn
+response carries `live.notification_method` so clients don't have to
+hard-code the brand.
+
+Status payloads emitted by the live plugin: `started` (synthetic, on plugin
+attach) → `preparing` → `scanning` → `auditing` → `cleanup` → `done` (or
+`aborted`) → `exited` (synthetic, fired from the live plugin's `at_exit`
+when the engine subprocess actually exits — only after `kill_instance` and
+only on a graceful unwind; SIGKILL skips it).
+
+Pass `live: false` to `spawn_instance` to opt out (poll `scan_progress`
+instead) -- recommended for non-MCP integrations and any application that
+disables the engine-side `live` plugin via `validate_options`.
+
+#### Auth
+
+Authentication is opt-in via `mcp_authenticate_with`. With a registered
+validator the server requires `Authorization: Bearer <token>` on every
+request and returns `401 Unauthorized` otherwise (RFC 6750 -- 
+`WWW-Authenticate: Bearer realm="MCP", error=…`). The resolved principal is
+stashed at `env['cuboid.mcp.auth']` for downstream middleware.
+
+#### Resources & prompts
+
+`Cuboid::MCP` also wires the standard `resources/list` / `resources/read`
+and `prompts/list` / `prompts/get` MCP plumbing. Service modules can ship
+markdown / JSON resources (glossaries, options references, presets) and
+prompts (canned operator workflows) via `tools` / `prompts` / `resources`
+/ `read_resource` class methods on the registered handler. The Spectre /
+Apex umbrellas use this to ground AI clients without out-of-band knowledge
+-- the tool / prompt / resource descriptions ARE the docs.
+
 ## Examples
 
 ### MyApp
@@ -263,11 +344,125 @@ sleep 0.1 while sleepers.map(&:busy?).include?( true )
 
 _You can replace `host1` with `localhost` and run all examples on the same machine._
 
+### Driving an Application over MCP
+
+`mcp_app_tool` ships a top-level catalogue tool (no `instance_id`); 
+`mcp_service_for` ships per-instance tools whose first arg is `instance_id`.
+
+`sleeper_mcp.rb`:
+```ruby
+require 'cuboid'
+require 'mcp'
+
+# A top-level catalogue tool — no `instance_id` required.
+class Ping < MCP::Tool
+    tool_name   'ping'
+    description 'Connectivity check; returns "pong".'
+    input_schema(properties: {}, type: 'object')
+    def self.call( ** )
+        MCP::Tool::Response.new([{ type: 'text', text: 'pong' }])
+    end
+end
+
+# A per-instance tool routed to the engine identified by `instance_id`.
+module SleeperMCP
+    class HowLong < MCP::Tool
+        tool_name   'how_long'
+        description "Reports the sleeper's progress."
+        input_schema(
+            properties: { instance_id: { type: 'string' } },
+            required:   ['instance_id'],
+            type:       'object'
+        )
+
+        def self.call( instance_id:, server_context: nil, ** )
+            instance = server_context[:instance]
+            MCP::Tool::Response.new([{
+                type: 'text',
+                text: instance.progress.to_json
+            }])
+        end
+    end
+
+    TOOLS = [HowLong].freeze
+    def self.tools; TOOLS; end
+end
+
+class Sleeper < Cuboid::Application
+    mcp_app_tool        Ping
+    mcp_service_for     :sleeper, SleeperMCP
+
+    def run; sleep options['time']; end
+end
+
+# Spawn the MCP server (Streamable HTTP at /mcp on the default RPC port).
+Sleeper.spawn(:mcp)
+```
+
+```bash
+bundle exec ruby sleeper_mcp.rb
+```
+
+In another shell, the standard MCP handshake:
+
+```bash
+SID=$(curl -sS -i -X POST http://127.0.0.1:7331/mcp \
+    -H 'Content-Type: application/json' \
+    -H 'Accept: application/json, text/event-stream' \
+    --data '{"jsonrpc":"2.0","id":1,"method":"initialize",
+             "params":{"protocolVersion":"2025-06-18",
+                       "capabilities":{},
+                       "clientInfo":{"name":"curl","version":"0"}}}' \
+    | awk -F': ' '/[Mm]cp-[Ss]ession-[Ii]d/ {gsub(/\r/,"",$2); print $2}')
+
+curl -sS -X POST http://127.0.0.1:7331/mcp \
+    -H "Mcp-Session-Id: $SID" \
+    -H 'Content-Type: application/json' \
+    -H 'Accept: application/json, text/event-stream' \
+    --data '{"jsonrpc":"2.0","method":"notifications/initialized"}'
+
+# 1. The catalogue tool — no instance_id needed.
+curl -sS -X POST http://127.0.0.1:7331/mcp \
+    -H "Mcp-Session-Id: $SID" -H 'Content-Type: application/json' \
+    -H 'Accept: application/json, text/event-stream' \
+    --data '{"jsonrpc":"2.0","id":2,"method":"tools/call",
+             "params":{"name":"ping","arguments":{}}}'
+# → "pong"
+
+# 2. Spawn an instance, then call the per-instance tool.
+SPAWN=$(curl -sS -X POST http://127.0.0.1:7331/mcp \
+    -H "Mcp-Session-Id: $SID" -H 'Content-Type: application/json' \
+    -H 'Accept: application/json, text/event-stream' \
+    --data '{"jsonrpc":"2.0","id":3,"method":"tools/call",
+             "params":{"name":"spawn_instance",
+                       "arguments":{"options":{"time":5},"start":true}}}')
+IID=$(echo "$SPAWN" | sed -n 's/^data: //p' | jq -r '.result.structuredContent.instance_id')
+
+curl -sS -X POST http://127.0.0.1:7331/mcp \
+    -H "Mcp-Session-Id: $SID" -H 'Content-Type: application/json' \
+    -H 'Accept: application/json, text/event-stream' \
+    --data "{\"jsonrpc\":\"2.0\",\"id\":4,\"method\":\"tools/call\",
+             \"params\":{\"name\":\"how_long\",\"arguments\":{\"instance_id\":\"$IID\"}}}"
+# → progress JSON
+
+# 3. Tear down.
+curl -sS -X POST http://127.0.0.1:7331/mcp \
+    -H "Mcp-Session-Id: $SID" -H 'Content-Type: application/json' \
+    -H 'Accept: application/json, text/event-stream' \
+    --data "{\"jsonrpc\":\"2.0\",\"id\":5,\"method\":\"tools/call\",
+             \"params\":{\"name\":\"kill_instance\",\"arguments\":{\"instance_id\":\"$IID\"}}}"
+```
+
+The `live` channel (SSE on `GET /mcp`) is attached automatically;
+omit it with `live: false` on `spawn_instance`.
+
 ## Users
 
 * [QMap](https://github.com/qadron/qmap) --  A distributed network mapper/security scanner powered by [nmap](http://nmap.org/).
 * [Peplum](https://github.com/peplum/peplum) -- A distributed parallel processing solution -- allows you to build Beowulf
 (or otherwise) clusters and even super-computers.
+* [Spectre Scan](https://try.spectre-scan.sh)
+* [Apex Recon](https://try.apex-recon.sh)
 
 ## License
 

data/cuboid.gemspec

@@ -52,6 +52,10 @@ Gem::Specification.new do |s|
     s.add_dependency 'sinatra', '>= 4.0'
     s.add_dependency 'sinatra-contrib', '>= 4.0'
 
+    # MCP (Model Context Protocol) server framework — Cuboid::MCP::Server
+    # mounts MCP::Server::Transports::StreamableHTTPTransport as a Rack app.
+    s.add_dependency 'mcp', '>= 0.15'
+
     # RPC client/server implementation.
     s.add_dependency 'toq'
 

data/lib/cuboid/application.rb

@@ -48,8 +48,8 @@ class Application
             true
         end
 
-        # Cleans up the framework; should be called after running the audit or
-        # after canceling a running scan.
+        # Cleans up the framework; should be called after running the application
+        # or after canceling a running instance.
         def clean_up
             return if @cleaned_up
             @cleaned_up = true
@@ -132,6 +132,81 @@ class Application
             @rest_services ||= {}
         end
 
+        # Register an MCP service handler. Mirrors `rest_service_for`:
+        # the application gem provides a module/class that exposes a
+        # set of tools and Cuboid::MCP::Server mounts them per-instance
+        # at `/instances/:instance/<name>` (just like REST mounts
+        # rest_service handlers at `/instances/:instance/<name>`).
+        #
+        # The handler must respond to `.tools`, returning an Array of
+        # `MCP::Tool` subclasses. Each tool's `call` receives a
+        # `server_context:` Hash containing at least `:instance` —
+        # the resolved RPC client for the engine instance the request
+        # is targeting.
+        #
+        # Example:
+        #
+        #     module MyApp::MCPHandler
+        #         class Ping < ::MCP::Tool
+        #             tool_name 'ping'
+        #             description 'Ping the application instance.'
+        #             def self.call(server_context:, **)
+        #                 server_context[:instance].some_application_method
+        #                 ::MCP::Tool::Response.new([{ type: 'text', text: 'pong' }])
+        #             end
+        #         end
+        #         TOOLS = [Ping].freeze
+        #         def self.tools; TOOLS; end
+        #     end
+        #
+        #     class MyApp < Cuboid::Application
+        #         mcp_service_for :my_service, MCPHandler
+        #     end
+        def mcp_service_for( name, handler )
+            mcp_services[name] = handler
+        end
+
+        def mcp_services
+            @mcp_services ||= {}
+        end
+
+        # Register an `MCP::Tool` subclass to ship at the top-level
+        # `/mcp` endpoint, alongside `CoreTools` (`list_instances`,
+        # `spawn_instance`, `kill_instance`) — i.e. NOT routed through
+        # the per-instance dispatcher and not requiring an
+        # `instance_id` argument. Use this for app-level catalog /
+        # metadata tools the client may want to consult before
+        # spawning anything.
+        #
+        # Example:
+        #
+        #     class MyApp < Cuboid::Application
+        #         mcp_app_tool ListChecks
+        #     end
+        def mcp_app_tool( tool_class )
+            mcp_app_tools << tool_class
+        end
+
+        def mcp_app_tools
+            @mcp_app_tools ||= []
+        end
+
+        # Register a bearer-token validator for the MCP transport. The
+        # block receives the token string and should return a truthy
+        # principal (typically a User record) on success or nil/false
+        # on failure. See Cuboid::MCP::Auth for the request flow.
+        #
+        # Without a registered validator the auth middleware passes
+        # every request through — keeps smoke tests / pre-auth-layer
+        # deployments simple.
+        def mcp_authenticate_with( &block )
+            @mcp_auth_validator = block
+        end
+
+        def mcp_auth_validator
+            @mcp_auth_validator
+        end
+
         def agent_service_for( name, service )
             agent_services[name] = service
         end
@@ -200,6 +275,12 @@ class Application
                     options.merge( options: { paths: { application: source_location } } ),
                     &block
                 )
+            when :mcp
+                return Processes::Manager.spawn(
+                    :mcp,
+                    options.merge( options: { paths: { application: source_location } } ),
+                    &block
+                )
             end
 
             Processes.const_get( const ).spawn(
@@ -282,7 +363,7 @@ class Application
     #
     #   Framework statistics:
     #
-    #   *  `:runtime`       -- Scan runtime in seconds.
+    #   *  `:runtime`       -- Application runtime in seconds.
     def statistics
         {
             runtime: @start_datetime ? (@finish_datetime || Time.now) - @start_datetime : 0,

data/lib/cuboid/mcp/auth.rb

@@ -0,0 +1,99 @@
+require 'json'
+
+module Cuboid
+module MCP
+
+# Bearer-token authentication middleware for the MCP transport.
+#
+# Application gems opt in by registering a validator block on their
+# Cuboid::Application subclass:
+#
+#     class MyApplication < Cuboid::Application
+#         mcp_authenticate_with do |token|
+#             # Return truthy (typically the User record) on success,
+#             # nil/false on failure.
+#             User.find_by( api_token: token )
+#         end
+#     end
+#
+# When no validator is registered the middleware passes every request
+# through — useful for smoke tests and for transports terminated
+# behind another auth layer (e.g. a reverse proxy).
+#
+# On success the resolved validator return value is stashed in
+# `env['cuboid.mcp.auth']` so downstream middleware / tooling can
+# look up the authenticated principal.
+#
+# Failure modes follow RFC 6750 — Bearer Token Usage:
+#   * Missing / malformed Authorization header → 401 + WWW-Authenticate
+#   * Token rejected by the validator           → 401 + WWW-Authenticate
+class Auth
+
+    REALM = 'MCP'.freeze
+
+    # Standard Bearer-prefix per RFC 6750 §2.1, case-insensitive.
+    BEARER_PREFIX = /\ABearer\s+/i
+
+    def initialize( app )
+        @app = app
+    end
+
+    def call( env )
+        validator = current_validator
+        return @app.call( env ) if validator.nil?
+
+        token = extract_token( env )
+        return unauthorized( 'invalid_request' )      if token.nil?
+
+        principal = safe_validate( validator, token )
+        return unauthorized( 'invalid_token' )        if !principal
+
+        env['cuboid.mcp.auth'] = principal
+        @app.call( env )
+    end
+
+    private
+
+    # Look up the validator at request time (not boot time) so
+    # applications can register / replace it after the server has
+    # already booted.
+    def current_validator
+        app = ::Cuboid::Application.application
+        return nil if app.nil?
+        return nil if !app.respond_to?( :mcp_auth_validator )
+        app.mcp_auth_validator
+    end
+
+    def extract_token( env )
+        header = env['HTTP_AUTHORIZATION'].to_s
+        return nil if header.empty?
+        return nil if header !~ BEARER_PREFIX
+        header.sub( BEARER_PREFIX, '' ).strip
+    end
+
+    # Wrap the validator call so an exception in user code becomes a
+    # generic 401 rather than a 500 — leaking validator internals to
+    # an unauthenticated caller would be a footgun.
+    def safe_validate( validator, token )
+        validator.call( token )
+    rescue => e
+        warn "[Cuboid::MCP::Auth] validator raised: #{e.class}: #{e.message}"
+        nil
+    end
+
+    def unauthorized( error )
+        body = { jsonrpc: '2.0', error: { code: -32001, message: error } }.to_json
+        [
+            401,
+            {
+                'content-type'     => 'application/json',
+                'www-authenticate' => %(Bearer realm="#{REALM}", error="#{error}")
+            },
+            [body]
+        ]
+    end
+
+end
+
+end
+end