EDAMAME Endpoint Threat Models

Table of Contents

• 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

Overview

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.

Database Generation and Management

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.

Port Vulnerability Database

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.

Vendor Vulnerability Database

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.

Device Profile Database

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

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

Whitelist Database

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).

Blacklist Database

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.

Database Integrity and Updates

All EDAMAME databases include:

• A timestamp indicating when they were last updated
• A cryptographic signature for integrity verification
• A structured format that supports easy parsing and validation

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

Threat Dimensions

Security threats are categorized along 5 key dimensions:

Dimension	Description
Applications	Application authorizations, EPP/antivirus, ...
Network	Network configuration, exposed services, ...
Credentials	Password policies, biometrics, 2FA, ...
System Integrity	MDM profiles, jailbreaking, 3rd party administrative access, ...
System Services	System configuration, service vulnerabilities, ...

Naming Conventions

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

Model Structure

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

JSON Format

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": { ... }
    }
  ]
}

Key Fields

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

Implementation Types

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

System Checks

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

Command Line Checks

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

Business Rules

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