• Overview
• Database Generation and Management
  • Port Vulnerability Database
  • Vendor Vulnerability Database
  • Device Profile Database
  • Whitelist Database
  • Sensitive Path Database
  • Blacklist Database
  • Database Integrity and Updates
• Threat Dimensions
• Naming Conventions
• Model Structure
  • JSON Format
  • Key Fields
• Implementation Types
  • System Checks
  • Command Line Checks
  • Business Rules
• How to Develop and Test Threat Models
• Platform Coverage
• Security Assessment
  • Severity Classification
  • Compliance Frameworks
• Privacy Protection
  • Important Note on Business Rules
• Additional Features
  • Internationalization
  • Implementation Details
  • Remediation Guidance
• Score Calculator
• EDAMAME Ecosystem

This repository contains the threat models used by the EDAMAME Security application to compute its Security Score. These models are based on industry-standard benchmarks including NIST and CIS, as well as other authoritative sources.

The EDAMAME Security platform leverages these models to provide comprehensive security posture assessment while ensuring user privacy and preventing administrative overreach.

EDAMAME Security relies on several specialized databases that power its detection capabilities. These databases are maintained through a combination of automated scripts and manual curation to ensure accuracy and relevance.

The lanscan-port-vulns-db.json database catalogs vulnerabilities associated with TCP ports. This database is automatically generated and updated using the build-port-vulns-db.py script which:

1. Retrieves port service descriptions from Nmap's service database
2. Queries the MITRE CVE database for vulnerabilities associated with each port
3. Filters vulnerabilities to include only those from the past 5 years
4. Verifies that vulnerability descriptions explicitly mention the port
5. Adds metadata including service names, descriptions, and protocol information
6. Generates a cryptographic signature for database integrity verification

The database is updated monthly via a scheduled GitHub Actions workflow (.github/workflows/update_vulns_db.yml).

The port vulnerability database enables EDAMAME Security to identify potentially vulnerable services running on endpoints within a network scan.

Similarly, the lanscan-vendor-vulns-db.json database tracks vulnerabilities associated with hardware vendors. It is generated by build-vendor-vulns-db.py which:

1. Retrieves vendor information from Wireshark's OUI database
2. Processes and normalizes vendor names for consistent matching
3. Queries the MITRE CVE database for vulnerabilities associated with each vendor
4. Retains only recent CVEs (past 4 years)
5. Organizes vulnerabilities by vendor with appropriate metadata
6. Signs the database for integrity verification

Like the port vulnerability database, this database is updated monthly via the same GitHub Actions workflow (.github/workflows/update_vulns_db.yml).

This database helps EDAMAME Security evaluate potential risks associated with specific hardware vendors detected on the network.

The lanscan-profiles-db.json file contains rules for identifying device types based on their network characteristics. Unlike the vulnerability databases, this is primarily maintained manually to ensure accurate device type identification. The database:

1. Defines device types (printers, routers, IoT devices, etc.)
2. Contains logical rules for identifying each device type based on:
   • Open ports
   • mDNS service advertisements
   • Vendor information
   • Hostnames
   • Service banners
3. Implements complex condition trees using AND/OR logical operators
4. Supports negation of conditions for more precise matching

Evaluation semantics:

• Rules are evaluated strictly in the JSON order; the engine returns the first matching device_type (first-match-wins).
• To avoid ambiguous classifications, design rules so only one device_type matches a given device. The validation script flags overlapping matches across multiple device types.

This database powers EDAMAME Security's device identification capabilities, allowing it to recognize and categorize devices on local networks.

The whitelists-db.json database defines allowable network connections for different environments and scenarios. It contains:

1. Base whitelists for essential EDAMAME functionality
2. Specialized whitelists for development and CI/CD environments
3. Platform-specific whitelists (macOS, Linux, Windows)
4. Hierarchical definitions with inheritance support

Currently, the database defines the following key whitelists:

• edamame: Base list for core application connections (backend APIs, analytics, IP services).
• builder: Extends edamame for development environments (package repositories, cloud services, CDNs).
• github: Extends builder for GitHub-related connections (GitHub domains, Azure IPs for Actions).
• github_macos, github_ubuntu, github_windows: Extend github with platform-specific connections needed in CI/CD environments (e.g., Homebrew/Apple services for macOS, Ubuntu/Microsoft repositories for Linux).

The sensitive-paths-db.json database defines file paths that indicate credential stores, secrets, and other high-value targets on a host. The EDAMAME vulnerability detector correlates these paths with network session data in three ways:

• token_exfiltration: Fires when an anomalous session (flagged by the iForest anomaly detector) has sensitive files open.
• skill_supply_chain: Fires when a blacklisted session (known-bad IP) has sensitive files open.
• credential_harvest: Fires when any session (regardless of anomaly score) has sensitive files spanning >= N distinct label categories (default N=3, configurable via credential_harvest_min_labels in cve-detection-params-db.json). This catch-all detects supply chain malware that uses normal-looking traffic patterns to exfiltrate harvested credentials.

The database contains three sections:

1. common_patterns: Cross-platform paths matched against L7 open_files in captured sessions. Covers SSH keys, cloud credentials (AWS, GCP, Azure), container configs (Docker, Kubernetes), package manager tokens (npm, PyPI), database credentials (PostgreSQL, MySQL), secret managers (Vault), git credentials, browser credential stores, cryptocurrency wallets, and environment files.
2. labels: Semantic groupings of paths (e.g. ssh, aws, gcp, vault, crypto) used by the vulnerability detector to classify which credential categories a process is accessing. The label count drives the credential_harvest check: multi-label findings (e.g. ssh + aws + kube simultaneously) indicate broad credential harvesting such as supply chain infostealers.
3. platform_patterns: OS-specific paths (e.g. /etc/shadow on Linux, Keychain on macOS, SAM/NTDS on Windows, crypto wallet Application Support / AppData paths).

The path list is informed by real-world supply chain attacks including the litellm 1.82.8 PyPI compromise (March 2026), AMOS infostealer campaigns, and MCPTox tool poisoning research.

This database is maintained manually. After editing, run python3 src/publish/update-models.py sensitive-paths-db.json to refresh the date and signature.

The cve-detection-params-db.json database stores check metadata and tuning parameters for the EDAMAME vulnerability detector. It is a cloud model updated via the same signature mechanism as other databases. Key contents:

• checks: Metadata (description template, severity, reference) for each vulnerability check: token_exfiltration, skill_supply_chain, credential_harvest, sandbox_exploitation, file_system_tampering, and sensitive_material_egress.
• credential_harvest_min_labels: Minimum number of distinct credential label categories a process must access to trigger the credential_harvest finding (default: 3). This threshold can be tuned without shipping a new binary.
• secret_content_scan_max_bytes / secret_content_min_hits / recent_sensitive_open_file_ttl_secs: Tunables for secret-like content scanning and how long recent sensitive open-file evidence remains eligible for correlation.
• ci_runner_process_name_prefixes: CI provisioning daemon name prefixes (for example provjobd) that the sandbox lineage detector may suppress when the matching process is also running from a suspicious temp lineage on ephemeral build hosts.
• suspicious_parent_path_patterns: Path prefixes that trigger sandbox_exploitation (for example /tmp/, /var/tmp/, \Temp\).
• generic_reuse_tokens / generic_application_tokens: Tokens filtered from process identity during finding deduplication and self-access suppression.
• init_process_names: Process names excluded from sandbox lineage checks (e.g. launchd, systemd).
• benign_temp_artifact_suffixes: File suffixes treated as routine FIM churn unless the writing process lineage is suspicious.
• application_storage_patterns / packaged_application_*_patterns: App-owned storage roots and install-layout heuristics used for self-access suppression.
• credential_store_patterns: Platform-specific credential-store path buckets for Keychain, keyring, KWallet, and Windows Vault detection.
• trusted_credential_helpers: Configurable allowlists for platform credential helpers and system daemons (for example securityd, assistantd, CommCenter, networkserviceproxy) so benign OS maintenance can be tuned from the model instead of hardcoded in Rust.

After editing, run python3 src/publish/update-models.py cve-detection-params-db.json to refresh the date and signature, then update the fallback embed in edamame_foundation/src/cve_detection_params_db.rs.

The blacklists-db.json database catalogs known malicious or unwanted IP addresses and ranges sourced from public blocklists. This database is automatically generated and updated by the build-blacklists.py script, which:

1. Downloads IP lists from predefined sources. Currently, it uses the firehol_level1 list (https://raw.githubusercontent.com/ktsaou/blocklist-ipsets/master/firehol_level1.netset), known for basic protection with minimal false positives.
2. Parses the downloaded content, removing comments and extracting IP addresses or CIDR ranges.
3. Structures the data, including metadata such as the source URL, description, and last update time for each list.
4. Stores the collected IP ranges within the JSON structure.
5. Generates a cryptographic signature based on the blacklist content for integrity verification.

The database is updated daily via a scheduled GitHub Actions workflow (.github/workflows/update_blacklists_db.yml).

This database enables EDAMAME Security to identify connections to potentially harmful IP addresses.

All EDAMAME databases include:

• A timestamp (date) indicating when they were last updated (format: Month DDth YYYY)
• A cryptographic signature (signature) for integrity verification, plus a .sig sidecar file containing the same value
• A structured format that supports easy parsing and validation

Validation and update rules:

• The validator recomputes the signature by hashing the JSON with the signature field blanked (sorted keys) and compares it to the stored value and .sig sidecar.

Important – manual step required: after any change to a database or threat-model JSON file, you must run the update script locally before committing:

python3 src/publish/update-models.py <file1.json> [file2.json ...]

This script refreshes the date, recomputes the cryptographic signature, and writes/updates the .sig side-car file. The CI validation workflow will fail if these values are stale or missing.

These databases are designed to be updated seamlessly from trusted sources while maintaining user privacy and security.

Security threats are categorized along 5 key dimensions:

Threat names follow these conventions:

• Describe the threat directly (not its remediation)
• No hyphens (-)
• Spaces are preferred over underscores (_)
• No special characters
• Lowercase except for acronyms and commercial names
• Example: Chrome not uptodate

Each threat model is structured as a JSON file that defines:

1. Threat metadata: Information about the threat, including its name, description, severity, and impact
2. Detection logic: The checks and conditions used to detect the presence of the threat
3. Remediation guidance: Recommended actions to mitigate the threat
4. References: Links to standards, benchmarks, and other sources of information

Each threat model file follows a standardized format:

{
  "name": "threat model [Platform]",
  "extends": "none",
  "date": "Last update date",
  "signature": "Cryptographic signature of the model",
  "metrics": [
    {
      "name": "Threat name",
      "metrictype": "bool",
      "dimension": "One of the 5 dimensions",
      "severity": 1-5,
      "scope": "Platform-specific or generic",
      "tags": ["Compliance standards", "Benchmarks"],
      "description": [
        { "locale": "EN", "title": "Title", "summary": "Description" },
        { "locale": "FR", "title": "Titre", "summary": "Description" }
      ],
      "implementation": { ... },
      "remediation": { ... },
      "rollback": { ... }
    }
  ]
}

Top Level Properties:

• name: The unique identifier of the threat model
• extends: Inheritance model, if applicable
• date: Last update timestamp
• signature: Cryptographic signature for integrity verification
• metrics: Array of threat definitions

Metric Properties:

• name: The threat identifier
• metrictype: Type of measurement (typically boolean)
• dimension: The security dimension the threat belongs to
• severity: Impact rating from 1 (low) to 5 (critical)
• scope: Whether the threat is platform-specific or generic
• tags: Compliance references (e.g., CIS Benchmark, ISO 27001, SOC 2)
• description: Localized explanations of the threat
• implementation: Detection logic
• remediation: Steps to resolve the threat
• rollback: Steps to revert remediation if needed

Threat models employ different detection methods depending on the nature of the security check:

Direct checks of system configuration, file presence, or settings that can be evaluated through standard APIs.

Safe, predefined commands that gather information about the system state. These commands are carefully vetted to ensure they cannot cause harm to the system.

Specialized checks that execute local scripts in userspace, leveraging the EDAMAME_BUSINESS_RULES_CMD

The CLI export/import utilities and the GitHub-based test workflow let you edit metrics with full fidelity while validating them on hosted runners.

1. Edit the tracked scripts directly The repository already contains every metric script under threat model */<metric>/implementation.(sh|ps) (and remediation/rollback counterparts). Treat these files as the source of truth—add comments, restructure logic, and test locally as needed. Only run export.py if you need to regenerate the folders from a pristine JSON (e.g., initial checkout) or to diff what changed; the normal workflow never requires exporting again.

2. Re-import scripts into the JSON

   python3 src/cli/import.py threatmodel-macOS.json
   python3 src/cli/import.py threatmodel-Windows.json

   The importer normalizes newlines, strips shell headers before embedding them back into JSON, and ensures multi-line commands are stored losslessly. Because legacy agents expect a single-line target, the importer wraps each script in a reversible launcher:

   • macOS/Linux: printf '%s\n' … | /bin/bash prints every original line verbatim and pipes it into bash, so heredocs, comments, and arrays survive the round trip intact.
   • Windows: a PowerShell array of quoted lines is joined with `n newlines and passed to Invoke-Expression, yielding the original script text before execution. The exporter detects these wrappers and recreates the readable .sh/.ps files automatically, so you never need to hand-edit JSON.

3. Run the hosted test suite

   ./tests/run-tests.sh

   This helper script checks for git/gh, snapshots your working tree (even with uncommitted changes), pushes a temporary branch, triggers .github/workflows/test_models.yml, streams the run, and prints any [ERROR]/Error: lines found in the CI logs before cleaning up.

4. Refresh signatures before committing

   python3 src/publish/update-models.py threatmodel-macOS.json threatmodel-Windows.json

   This updates the date, signature, and .sig sidecars required by CI.

5. (Optional) Bake local models into edamame_foundation for development If you want to test the new JSONs inside the Rust binaries before publishing them, run the embedding script from the edamame_foundation repo:

   cd ../edamame_foundation
   ./update-threats.sh --local macOS
   ./update-threats.sh --local Linux
   ./update-threats.sh --local Windows

   The --local flag tells the script to read the sibling ../threatmodels/threatmodel-*.json files instead of fetching from GitHub, so you can immediately cargo check/cargo test against your edits. You can omit the OS argument to regenerate every platform in one go.

Following this loop keeps the JSON models, extracted scripts, and CI validation in sync.

The score_calculator repository provides a standalone Python utility that computes the EDAMAME Security Score from these threat models. It implements the same severity-weighted scoring algorithm as the production Rust code in edamame_foundation, producing identical results.

Given a platform and a set of check results (which threats are active vs. inactive), it computes:

• Per-dimension scores (0-100%) for each of the 5 security dimensions
• Overall score (0-100%) and star rating (0.0-5.0)
• Compliance percentages per tag prefix (CIS Benchmark, ISO 27001/2, SOC 2, etc.)

# Fetch the macOS threat model and compute the score with specific threats remediated
python score_calculator.py --platform macOS --inactive "local firewall disabled" "SIP disabled"

# Best case score
python score_calculator.py --platform macOS --all-inactive

# JSON output
python score_calculator.py --platform macOS --all-inactive --json

See the score_calculator README for full usage documentation.