Public documentation for the EDAMAME Core API -- the closed-source Rust engine that powers the EDAMAME security platform.

EDAMAME Core provides cross-platform security assessment, threat remediation, network visibility, AI-powered automation, and compliance reporting through a unified API surface. It is consumed by GUI applications (Flutter), CLI tools, and external AI agents via MCP.

EDAMAME Core is available for OEM integration. If you are interested in embedding EDAMAME's security engine into your own product, contact EDAMAME Technologies.

For the full ecosystem overview, see the EDAMAME Technologies profile.

1. Architecture
2. Language and Build
3. Feature Flags
4. Multi-Platform Support
5. API Overview
6. Event System
7. gRPC Interface
8. MCP Server -- see also MCP.md for complete tool reference
9. Integration Patterns
10. API Reference
11. OEM Licensing

EDAMAME Core follows a strict three-layer architecture:

+------------------------------------------------------------------+
|                    Consumer Layer                                |
|   Flutter Bridge (GUI)  |  gRPC (CLI)  |  MCP (AI Agents)        |
+------------------------------------------------------------------+
                              |
                              v
+------------------------------------------------------------------+
|                      API Layer (api_*.rs)                        |
|  - Thin wrappers around business logic                           |
|  - Type conversions (internal -> serializable API types)         |
|  - RPC endpoint registration via rpc!() macro                    |
|  - Background task orchestration                                 |
+------------------------------------------------------------------+
                              |
                              v
+------------------------------------------------------------------+
|               Core Manager Layer (core_manager_*.rs)             |
|  - ALL business logic                                            |
|  - State management                                              |
|  - Guard protection for concurrent access                        |
|  - Event triggering                                              |
+------------------------------------------------------------------+
                              |
                              v
+------------------------------------------------------------------+
|                    Core State (core_state.rs)                    |
|  - Shared state containers (Arc<CustomRwLock<>>)                 |
|  - Thread-safe concurrent access                                 |
|  - Feature-gated fields                                          |
+------------------------------------------------------------------+

• API Layer is always thin: no business logic, only type conversion and delegation
• CoreManager owns all workflows, validation, and orchestration
• CoreState wraps all shared data in Arc<CustomRwLock<>> for thread safety
• Events broadcast state changes to all consumers (Flutter streams, gRPC streams, internal listeners)

EDAMAME Core is written in Rust using the Tokio async runtime. It compiles as a static library (for Apple platforms), dynamic library (for Windows/Linux/Android), or standalone binary (for CLI tools).

# Default build (with Flutter bridge)
cargo build

# Standalone build (CLI tools, no Flutter)
cargo build --features standalone

# macOS CLI with Swift linking
cargo build --features swiftrs

[lib]
crate-type = ["staticlib", "cdylib", "lib"]

• staticlib: Apple platforms (macOS, iOS) -- linked into Xcode projects
• cdylib: Windows, Linux, Android -- dynamic library for Flutter or standalone use
• lib: Rust library for direct linking (CLI tools like edamame_posture, edamame_cli)

Feature flags control which capabilities are compiled into the binary:

default = ["userdefaults", "pwned", "flodbadd", "trust", "agentic", "mcp"]

mcp --> agentic --> [oauth2, jsonwebtoken, webbrowser, async-stream]
standalone --> [edamame_foundation/packetcapture, flodbadd/packetcapture, flodbadd/asyncpacketcapture]

EDAMAME Core targets all major desktop and mobile platforms through conditional compilation:

Platform-specific functionality is isolated behind #[cfg(target_os = "...")] gates:

• macOS/iOS: Native Swift integration via swift-rs for system APIs (notifications, UserDefaults, keychain)
• Windows: Windows Service integration, Npcap for network capture
• Linux: eBPF support for zero-copy packet capture and process attribution
• Android: JNI integration for native Android APIs

EDAMAME Security is a Flutter desktop/mobile application that consumes EDAMAME Core through flutter_rust_bridge:

Flutter (Dart)
    |
    v
flutter_rust_bridge (auto-generated FFI)
    |
    v
EDAMAME Core API Layer (api_*.rs)
    |
    v
CoreManager (business logic) --> CoreState (shared state)
    |
    v
Events --> StreamSink<u64> --> BehaviorSubject --> Flutter UI

Key integration points:

• Direct function calls: Each rpc!() endpoint becomes a callable Dart function (e.g., getScore(), remediate(), agenticProcessTodos())
• Reactive event streams: CoreEvent bitmasks flow through StreamSink to Dart BehaviorSubject, driving UI updates
• Bridge regeneration: After modifying API endpoints, run tear_down_walls.sh to regenerate the Flutter bridge code

EDAMAME Posture is a CLI tool for CI/CD and headless environments that links directly to EDAMAME Core as a Rust library:

edamame_posture (Rust binary)
    |
    v  (direct Rust function calls)
EDAMAME Core API Layer
    |
    v
CoreManager --> CoreState

Key integration points:

• Direct static linking: edamame_posture calls API functions directly (e.g., compute_score(), remediate(), get_sessions())
• Feature flag standalone: Built without Flutter bridge, enables packet capture
• Synchronous wrappers: Uses the _sync variants of async functions for CLI convenience
• Exit codes: Translates API results into CI/CD-compatible exit codes (0=success, 1=policy fail, 2=server error, 3=param error, 4=timeout)

Example Posture CLI commands and the API calls they map to:

EDAMAME CLI provides dynamic RPC access to the entire EDAMAME Core API surface:

edamame_cli (Rust binary)
    |
    v  (dynamic RPC dispatch)
rpc_call(method_name, json_args) --> EDAMAME Core Handler Registry
    |
    v
API Layer --> CoreManager --> CoreState

Key integration points:

• Method discovery: list-methods and get-method-info enumerate all registered RPC endpoints at runtime
• Dynamic invocation: rpc <method> [json_args] calls any API method by name with JSON arguments
• Interactive REPL: interactive mode for exploring the API
• Remote RPC: Can connect to a running EDAMAME Core instance over TLS-secured gRPC

Example EDAMAME CLI usage:

# List all available API methods
edamame-cli list-methods

# Get method signature and types
edamame-cli get-method-info get_score

# Call API methods with JSON arguments
edamame-cli rpc get_score '["true"]'
edamame-cli rpc get_device_info --pretty
edamame-cli rpc remediate '["firewall_disabled", "false"]'

# Interactive exploration
edamame-cli interactive

All API methods are registered via the rpc!() macro, which generates:

1. Async implementation (method_name_async()) -- the actual function
2. Handler -- registered in the handler registry for gRPC dispatch
3. Remote RPC wrappers -- for calling a remote EDAMAME Core instance
4. API metadata -- parameter names, types, and return type for discovery

// Declaration
rpc!(get_score(complete_only: bool) -> ScoreAPI);

// Generated async function (implemented by developer)
pub async fn get_score_async(complete_only: bool) -> ScoreAPI {
    CORE_MANAGER.read().await.get_score(complete_only).await
}

// Auto-generated: handler, remote RPC wrappers, metadata registration

EDAMAME Core uses a bitmask-based event system for broadcasting state changes. Each event is a power of 2, allowing efficient OR-combined event masks.

Events are delivered to all registered consumers:

• Flutter: StreamSink<u64> delivering to Dart BehaviorSubject
• gRPC: Server-streaming RPC (subscribe_to_events)
• Internal: mpsc::Sender channels for in-process listeners

See EVENTS.md for the complete event reference.

// Trigger an event from CoreManager
event_manager.trigger_event(CoreEvent::ScoreCompleted);

// Events are OR-combined for efficient delivery
// A consumer receiving value 16777224 means:
//   ScoreCompleted (16777216) | ConnectionSuccess (8) both fired

EDAMAME Core exposes a gRPC server for remote API access and event streaming. This is the interface used by edamame_cli and can be used by any gRPC client.

syntax = "proto2";
package edamame;

message HelperRequest {
  required string ordertype = 1;
  required string subordertype = 2;
  required string arg1 = 3;
  required string arg2 = 4;
  required string signature = 5;
  required string version = 6;
}

message HelperResponse {
  required string output = 1;
}

service EDAMAMEHelper {
  rpc Execute(HelperRequest) returns (HelperResponse);
}

Client (edamame_cli / custom)
    |
    | TLS (mTLS with client certificates)
    v
gRPC Server (api_rx.rs)
    |
    v
HANDLER_REGISTRY.get(method_name)
    |
    v
API Handler --> CoreManager --> Response (JSON serialized)

• mTLS: Client and server certificates for mutual authentication
• Certificate configuration via environment variables:
  • EDAMAME_CA_PEM -- Certificate Authority
  • EDAMAME_CLIENT_PEM -- Client certificate
  • EDAMAME_CLIENT_KEY -- Client private key

Clients can subscribe to real-time events via server-streaming RPC:

Client --> subscribe_to_events() --> Stream<u64>
                                      |
                                      v
                              Bitmask of fired events

EDAMAME Core includes an MCP (Model Context Protocol) server, enabling external AI assistants (like Claude Desktop, n8n, or custom agents) to interact with the security platform.

The MCP server supports two authentication modes:

1. Per-client credentials (app-mediated pairing): Desktop clients POST to the unauthenticated /mcp/pair endpoint with client metadata. The user approves the request in the host app UI. The client receives an edm_mcp_... credential and uses it as Authorization: Bearer edm_mcp_.... See MCP.md for pairing endpoint details.

2. Shared PSK (CLI/headless): A legacy Bearer token passed at server start. Used by CLI tools, provisioning scripts, and automation. The PSK can be provided via the EDAMAME_MCP_PSK environment variable or stored in ~/.edamame_psk (owner-read/write only, chmod 600).

For edamame_posture, generate a PSK with:

edamame_posture background-mcp-generate-psk

For the EDAMAME Security desktop app, configure credentials under AI tab > MCP Server Settings (pairing UI or shared PSK).

See MCP.md for the complete MCP tools reference with parameters, return types, and L7 session field documentation.

Observer-independence policy (CRITICAL): The reasoning plane (LLM agent) must not be able to silence security findings about its own behavior. Therefore, the MCP surface for divergence and vulnerability findings is read-only. Dismissal mutation operations (dismiss_*, undismiss_*, dismiss_*_with_scope, clear_divergence_state, clear_vulnerability_history, reset_vulnerability_suppressions, remove_agentic_dismissal_rule, set_agentic_dismissal_rule_severity_ceiling, reset_agentic_dismissal_rules, clear_agentic_dismissal_audit_log) are operator-only via the EDAMAME app UI (AI tab > Dismissal rules) and the edamame_cli RPC surface. The corresponding RPC endpoints remain available -- only their MCP tool exposure is removed.

Lifecycle controls (start_divergence_engine, start_vulnerability_detector, agentic_set_auto_processing, start_file_monitor, stop_file_monitor) are direct RPC/CLI control plane methods and are intentionally not exposed via MCP tools either.

Behavioral-model payloads use the v3 schema:

• expected dimensions: expected_traffic, expected_sensitive_files, expected_lan_devices, expected_local_open_ports, expected_process_paths, expected_parent_paths, expected_grandparent_paths, expected_open_files, expected_l7_protocols, expected_system_config
• negative dimensions: not_expected_traffic, not_expected_sensitive_files, not_expected_lan_devices, not_expected_local_open_ports, not_expected_process_paths, not_expected_parent_paths, not_expected_grandparent_paths, not_expected_open_files, not_expected_l7_protocols, not_expected_system_config
• scope filters: scope_process_paths, scope_parent_paths, scope_grandparent_paths, scope_any_lineage_paths
• expected traffic: domain-suffix (host:port) or ASN (asn:OWNER_SUBSTRING)

mcp_start_server(port, psk, enable_cors, listen_all_interfaces) -> String
mcp_stop_server() -> String
mcp_get_server_status() -> String
mcpApprovePairing(request_id: String) -> String
mcpRejectPairing(request_id: String) -> String
mcpListPairedClients() -> String
mcpGetPendingPairingRequests() -> String
mcpRevokePairedClient(client_id: String) -> String
mcpRotatePairedClient(client_id: String) -> String

PSK generation is available via the Posture CLI: edamame-posture mcp-generate-psk

Used by EDAMAME Security.

Flutter App
    |-- flutter_rust_bridge (FFI) --> EDAMAME Core (staticlib/cdylib)
    |-- Event streams via StreamSink
    |-- Direct function calls to all API endpoints
    |-- Full feature set (all default features enabled)

Build: cargo build (default features, with Flutter bridge)

Used by EDAMAME Posture.

edamame_posture (Rust binary)
    |-- Links edamame_core as Rust library dependency
    |-- Calls API functions directly (no FFI overhead)
    |-- Built with `standalone` feature (no Flutter, enables packet capture)
    |-- Translates results to exit codes for CI/CD

Build: cargo build --features standalone

Used by EDAMAME CLI.

edamame_cli (Rust binary)
    |-- Links edamame_core as Rust library dependency
    |-- Dynamic method discovery via API_REGISTRY
    |-- Calls any method by name with JSON arguments
    |-- Interactive REPL for exploration
    |-- Can also connect to remote instances via gRPC

Build: cargo build --features standalone,swiftrs (macOS) or cargo build --features standalone (other)

Used by Claude Desktop, n8n, or custom AI agents.

AI Agent (Claude Desktop / n8n / custom)
    |-- Streamable HTTP (localhost:3000)
    |-- Bearer token authentication (per-client credential or shared PSK)
    |-- Tool calls: advisor_get_todos, agentic_process_todos, etc.
    |-- Human-in-the-loop: agents escalate risky actions

Configuration: Start MCP server via mcp_start_server() API call or edamame-posture mcp-start. Use app-mediated pairing for per-client credentials, or shared PSK for CLI/headless.

Complete list of all RPC-registered API methods, organized by domain. Each method is callable via:

• Direct Rust function call (CLI tools)
• Flutter bridge (GUI app)
• gRPC RPC dispatch (remote clients)
• MCP tools (AI agents, for selected methods)

See API_REFERENCE.md for the full API reference with parameter types and descriptions.

System lifecycle, device information, and platform management.

Security scoring, threat detection, and remediation.

LAN scanning, packet capture, session analysis, whitelists/blacklists, and anomaly detection.

Every session returned by get_sessions and related methods includes deep L7 process attribution fields. See MCP.md for the complete field reference.

Key fields: pid, process_name, process_path, cmd, cwd, parent_pid, parent_process_name, parent_process_path, parent_cmd, parent_script_path, grandparent_pid, grandparent_process_name, grandparent_process_path, grandparent_cmd, grandparent_script_path, spawned_from_tmp, open_files, memory, cpu_usage, disk_usage.

• Process lineage: Full parent and grandparent chain for detecting script-based and interpreter-wrapped attacks
• Sensitive file detection: SSH keys, credentials, keychains tracked in open_files (sticky across refresh cycles)
• Temp-origin detection: spawned_from_tmp flags processes originating from /tmp/, /var/tmp/, /dev/shm/
• Refresh cycles: Full L7 refresh every 5 minutes; sensitive files re-scanned every 30s (Linux), 60s (macOS), 120s (Windows)

Email breach monitoring via HaveIBeenPwned integration. Supports dynamic add/remove of monitored emails via add_pwned_email and remove_pwned_email, enabling runtime identity registration (e.g., from an AI agent's introspection loop). Also available as MCP tools (see MCP.md).

Domain connection, policy enforcement, and compliance reporting.

Security recommendations and AI-enriched advice.

AI-powered security automation with multiple LLM providers.

MCP server management and pairing (feature-gated: mcp).

Note: PSK generation (mcp_generate_psk) is provided by the EDAMAME Posture CLI, not by EDAMAME Core directly.

EDAMAME Core is closed source and available for OEM integration into third-party products. OEM partners receive:

• Pre-built libraries for all supported platforms (macOS, Windows, Linux, iOS, Android)
• API documentation and integration guides
• Feature flag configuration to include only the capabilities needed
• Technical support for integration

• The complete EDAMAME security engine as a linkable library
• All 175+ API methods across security scoring, network analysis, breach detection, AI automation, and compliance
• Cross-platform support from a single codebase
• Reactive event system for building responsive UIs
• gRPC interface for remote management
• MCP server for AI agent integration

For OEM licensing inquiries: EDAMAME Technologies

• EDAMAME Technologies -- Organization profile and ecosystem overview
• EDAMAME Security -- Flutter GUI application
• EDAMAME Posture CLI -- CI/CD security tool
• EDAMAME CLI -- RPC explorer and API access
• EDAMAME Foundation -- Open source security library
• EDAMAME Backend -- API data structures
• Threat Models -- Security benchmarks and policies
• Flodbadd -- Network visibility engine