meepsdk

README

libmeep Plugin SDK

Go helpers for authoring libmeep intel plugins.

Module path:

go get github.com/meepsec/libmeep-plugin-sdk@v1.1.0

Included Helpers

• Document: common NDJSON output shape consumed by libmeep.
• CleanDocument: convenience constructor for a successful scan with no issue.
• NewEncoder: newline-delimited JSON encoder wrapper.
• ScanInput: stdin scanner that routes PURLs and handles !flush.
• ParsePURL: basic package-url parsing for package plugins.
• NewResultCache: result cache for plugin authors, with in-memory, persistent SQLite, and automatic temporary SQLite spillover modes.
• PluginConfigID: reads the libmeep-provided plugin configuration id for namespacing persistent cache entries.

Minimal Plugin Shape

package main

import (
	"os"

	sdk "github.com/meepsec/libmeep-plugin-sdk"
)

func main() {
	encoder := sdk.NewEncoder(os.Stdout)
	_ = sdk.ScanInput(os.Stdin, sdk.InputHandler{
		PURL: func(purl string) error {
			return encoder.Encode(sdk.CleanDocument("example-plugin", purl))
		},
	})
}

Result Cache

Plugins can use NewResultCache to avoid repeated queries for the same PURL:

cache, err := sdk.NewResultCache(sdk.ResultCacheOptions{
	PluginConfigID: sdk.PluginConfigID("osv"),
})
if err != nil {
	return err
}
defer cache.Close()

if value, ok, err := cache.Get("pkg:npm/left-pad@1.3.0"); err != nil {
	return err
} else if ok {
	// Decode value and return the cached result.
	_ = value
}

_ = cache.Set("pkg:npm/left-pad@1.3.0", []byte(`{"cached":true}`))

By default, the cache is in-memory. If it grows beyond 5000 entries, the SDK automatically spills it into a temporary SQLite database and removes that file when the cache is closed.

For persistent reuse between plugin runs, pass a SQLite file path:

cache, err := sdk.NewResultCache(sdk.ResultCacheOptions{
	Path:           "/path/to/meep-plugin-cache.sqlite",
	PluginConfigID: sdk.PluginConfigID("fastosv"),
})

Persistent cache keys include both PluginConfigID and PURL, so multiple plugin configurations can share one database without colliding.

License

libmeep-plugin-sdk is licensed under the GNU Lesser General Public License v3.0 or later. See LICENSE.

Documentation

Index

• Constants
• func PluginConfigID(defaultValue string) string
• func ScanInput(r io.Reader, handler InputHandler) error
• type Document
  • func CleanDocument(pluginID, purl string) Document
• type Encoder
  • func NewEncoder(w io.Writer) *Encoder
  • func (e *Encoder) Encode(doc Document) error
• type InputHandler
• type PURL
  • func ParsePURL(value string) (PURL, bool)
• type ResultCache
  • func NewResultCache(opts ResultCacheOptions) (ResultCache, error)
• type ResultCacheOptions

Constants

const DefaultMaxMemoryCacheEntries = 5000

const PluginConfigIDEnv = "LIBMEEP_PLUGIN_CONFIG_ID"

const StatusScanned = "SCANNED"

Functions

func PluginConfigID

func PluginConfigID(defaultValue string) string

func ScanInput

func ScanInput(r io.Reader, handler InputHandler) error

Types

type Document

type Document struct {
	PluginID         string         `json:"plugin-id"`
	PURL             string         `json:"purl"`
	Status           string         `json:"status"`
	ResultCount      []int          `json:"resultCount,omitempty"`
	Malicious        *bool          `json:"malicious,omitempty"`
	MaliciousPackage *bool          `json:"maliciousPackage,omitempty"`
	SuspiciousScore  *float64       `json:"suspiciousScore,omitempty"`
	VulnerabilityIDs []string       `json:"vulnerabilityIDs,omitempty"`
	IntelSpecific    map[string]any `json:"intel-specific,omitempty"`
}

func CleanDocument

func CleanDocument(pluginID, purl string) Document

type Encoder

type Encoder struct {
	// contains filtered or unexported fields
}

func NewEncoder

func NewEncoder(w io.Writer) *Encoder

func (*Encoder) Encode

func (e *Encoder) Encode(doc Document) error

type InputHandler

type InputHandler struct {
	PURL  func(string) error
	Flush func() error
}

type PURL

type PURL struct {
	Type    string
	Name    string
	Version string
	Raw     string
}

func ParsePURL

func ParsePURL(value string) (PURL, bool)

type ResultCache

type ResultCache interface {
	Get(purl string) ([]byte, bool, error)
	Set(purl string, value []byte) error
	Close() error
}

func NewResultCache

func NewResultCache(opts ResultCacheOptions) (ResultCache, error)

type ResultCacheOptions

type ResultCacheOptions struct {
	Path             string
	PluginConfigID   string
	MaxMemoryEntries int
}