Grok Build Source Course · 12 / 21

Marketplace：Discovery, Installation, and Execution Layers

A catalog can surface plugins, an installer can copy or clone them, and the runtime still needs to evaluate enabled status and trust. Only by separating these three layers can you see the real security boundaries of a plugin ecosystem.

Indexed + FallbackManifestInstall RegistryPer Plugin Root Trust
01 / OBJECTIVES

Lesson Objectives

Reconstruct the Discovery Chain

Explain index-first, filesystem fallback, manifest parsing, and source precedence.

Separate Four States

Distinguish between discoverable, installed, enabled, and trusted — avoid collapsing everything into a single "installed" semantic.

Draw the Execution Boundary

Determine how skills, agents, hooks, MCP, and scripts are handled differently when a plugin is not trusted.

02 / CORE VISUAL

From Catalog to Runtime

03 / STRUCTURE

Real Structure of a Marketplace and Plugin

MARKETPLACE

Catalog answers "what's available"

marketplace-root/
├── .grok-plugin/
│   ├── marketplace.json
│   └── plugin-index.json
├── plugins/
│   └── sample-plugin/
└── default-skills/

Scanner reads the index first; if missing or invalid, it falls back to scanning plugins/*/. default-skills can be added as a virtual plugin in the results.

xai-grok-plugin-marketplace/src/scanner.rs · index.rs · catalog.rs
PLUGIN

Plugin answers "what's inside"

sample-plugin/
├── plugin.json
├── skills/*/SKILL.md
├── commands/
├── agents/
├── hooks/hooks.json
├── .mcp.json
└── scripts/

plugin.json is the preferred manifest; .grok-plugin/plugin.json and .claude-plugin/plugin.json are fallback locations. PluginManifest can override paths for skills, commands, agents, hooks, MCP, and LSP; after parsing, paths are validated to remain within the plugin root.

xai-grok-agent/src/plugins/manifest.rs · docs/hooks-and-plugins.md
04 / DISCOVERY

Two Discovery Chains, Each with Its Own Role

CLI override--plugin-dir
Highest source priority
Project.grok/plugins
Compatible with .claude
User$GROK_HOME/plugins
Installed plugins
Registrymarketplace provenance
git / local source
Config path[plugins].paths
Location affects trust

Key distinction: xai-grok-plugin-marketplace handles catalog, scanning, and installation; xai-grok-agent::plugins handles runtime discovery, deduplication, name conflicts, enabling, and trust. A record appearing in Marketplace does not mean the component is immediately executable.

05 / THREE GATES

Three Gates from Visible to Executable

1

Source and Path

MarketplaceRelativePath rejects absolute paths, parent-directory traversal, and out-of-bounds joins. Remote entries can be pinned by git ref or SHA.

2

Enabled State

Discovery config maintains enabled and disabled lists. Project- or user-scoped entries default to the disabled list; CLI override and config-path entries default to enabled. Users can adjust explicitly.

3

Execution Trust

Project plugins are authorized by canonical plugin root at single-plugin granularity. Trust records are written to ~/.grok/trusted-plugins.

06 / TRUST

Component Matrix for Untrusted Plugins

Component
Discovery
Execution When Untrusted
Skills / Agents
Metadata listable
Metadata-level discovery only
Hooks
Identifiable from manifest
Load and execution blocked
MCP Servers
Identifiable from config path
Command startup blocked
Scripts
Part of plugin content
Execution blocked
FAIL CLOSED

Path resolution failure treated as untrusted

match dunce::canonicalize(plugin_root) {
    Ok(path) => self.trusted.contains(&path),
    Err(_) => false,
}
TRUST SCOPE

Source affects initial trust determination

CLI override and user scope are marked trusted in the source; project scope requires explicit trust. Config paths under the user home may be auto-trusted; other locations still require authorization.

crates/codegen/xai-grok-agent/src/plugins/trust.rs · discovery.rs
07 / SOURCE

Installer Preserves Provenance; Catalog Makes No Scale Guarantees

PROVENANCE

Install records are traceable

Local Marketplace installs via managed install storage; remote entries are located via Git URL, ref, SHA, and subdir. InstallRegistry writes a MarketplaceProvenance.

xai-grok-plugin-marketplace/src/installer.rs
EVIDENCE LIMIT

Source proves the mechanism, not the ecosystem scale

The current code can prove the official source constant, multiple sources, catalog indexing, search, and install flow. It cannot prove plugin count, active authors, audit coverage, or growth rate — this page makes no such inferences.

xai-grok-plugin-marketplace/src/lib.rs · types.rs
08 / LAB

Lab: Build a Threat Model for a Plugin

35 MIN

Deliverable
Plugin skeleton and threat table

  1. Create a minimal plugin directory with a skill, hook, and MCP config; write the manifest.
  2. Create a Marketplace index entry and explain how the filesystem fallback works when the index is missing.
  3. List the four states — discoverable, installed, enabled, trusted — and diagram the allowed transitions.
  4. Design three attacks: path traversal, malicious project hook, same-name plugin hijacking; find the source-level guardrails for each.
  5. Identify one remaining risk and propose a solution: pre-install review, SHA pinning, or least privilege.
Takeaway

The core value of a plugin system is shaped equally by its capability surface and its trust surface. The catalog solves discovery, the installer handles persistence, and the runtime trust gate decides which components enter the execution chain.

Source snapshot note: This page is based on the local grok-build-main repository's xai-grok-plugin-marketplace and xai-grok-agent::plugins. The directory tree merges source-code defaults for teaching clarity; source precedence, path constraints, enable config, and trust behavior follow source semantics.