• Overview
• Database Generation and Management
  • Port Vulnerability Database
  • Vendor Vulnerability Database
  • Device Profile Database
  • Whitelist 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
• Platform Coverage
• Security Assessment
  • Severity Classification
  • Compliance Frameworks
• Privacy Protection
  • Important Note on Business Rules
• Additional Features
  • Internationalization
  • Implementation Details
  • Remediation Guidance
• 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 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 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'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_linux, 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 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 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