Security

The Security Manager component provides 4 tools for auditing device security posture, checking flash encryption status, and reading or burning eFuse values. These tools wrap esptool and espefuse CLI commands as async subprocesses.

esp_security_audit

Perform a comprehensive security audit of a connected ESP device. Gathers chip identity, flash encryption status, secure boot state, JTAG status, and eFuse summary into a single structured report.

Parameters

Name	Type	Default	Description
`port`	`str \| None`	`None`	Serial port or `socket://` URI. Required.

Example

result = await client.call_tool("esp_security_audit", {
    "port": "/dev/ttyUSB0"
})

Return Value

{
  "success": true,
  "port": "/dev/ttyUSB0",
  "chip_id": "0x00f01d83",
  "security_info": {
    "Secure Boot": "disabled",
    "Flash Encryption": "disabled"
  },
  "efuse_summary": {
    "MAC": "aa:bb:cc:dd:ee:ff",
    "FLASH_CRYPT_CNT": "0",
    "ABS_DONE_0": "0",
    "JTAG_DISABLE": "0"
  },
  "security_fuses": {
    "FLASH_CRYPT_CNT": "0",
    "ABS_DONE_0": "0",
    "JTAG_DISABLE": "0"
  },
  "posture": {
    "flash_encryption": "disabled",
    "secure_boot": "disabled",
    "jtag": "enabled (vulnerable)"
  }
}

The posture object provides a quick summary of the three primary security mechanisms. The security_fuses object contains the raw eFuse values for the following security-relevant fields:

eFuse	Controls
`FLASH_CRYPT_CNT`	Flash encryption enable/disable counter
`ABS_DONE_0`	Secure Boot v1 permanent enable
`ABS_DONE_1`	Secure Boot v2 permanent enable
`JTAG_DISABLE`	JTAG debug interface disable
`DISABLE_DL_ENCRYPT`	Disable flash encryption in download mode
`DISABLE_DL_DECRYPT`	Disable flash decryption in download mode
`DISABLE_DL_CACHE`	Disable flash cache in download mode
`FLASH_CRYPT_CONFIG`	Flash encryption configuration

esp_enable_flash_encryption

Check the current flash encryption status and provide guidance on enabling it. This tool reads the relevant eFuses but does not perform the actual burn — use esp_efuse_burn for that.

Parameters

Name	Type	Default	Description
`port`	`str \| None`	`None`	Serial port or `socket://` URI. Required.
`key_file`	`str \| None`	`None`	Path to an encryption key file. Stored in the response for reference only.

Example

result = await client.call_tool("esp_enable_flash_encryption", {
    "port": "/dev/ttyUSB0"
})

Return Value

When encryption is not enabled:

{
  "success": true,
  "port": "/dev/ttyUSB0",
  "flash_encryption_enabled": false,
  "FLASH_CRYPT_CNT": "0",
  "FLASH_CRYPT_CONFIG": "0",
  "message": "Flash encryption is NOT enabled. To enable, you need to: 1) Generate or provide an encryption key, 2) Burn FLASH_CRYPT_CNT and FLASH_CRYPT_CONFIG eFuses, 3) Flash encrypted firmware. WARNING: This is irreversible on real hardware. Test on QEMU first."
}

When encryption is already active:

{
  "success": true,
  "port": "/dev/ttyUSB0",
  "flash_encryption_enabled": true,
  "FLASH_CRYPT_CNT": "1",
  "FLASH_CRYPT_CONFIG": "0xf",
  "message": "Flash encryption is already enabled on this device."
}

esp_efuse_read

Read eFuse values from a device. Without a specific efuse_name, returns the full human-readable summary from espefuse summary. With efuse_name, returns just that field’s value.

eFuses are one-time-programmable bits that control chip security, MAC address, calibration data, and more. Reading is non-destructive.

Parameters

Name	Type	Default	Description
`port`	`str \| None`	`None`	Serial port or `socket://` URI. Required.
`efuse_name`	`str \| None`	`None`	Specific eFuse to read (e.g., `"MAC"`, `"FLASH_CRYPT_CNT"`). Returns full summary if omitted.

result = await client.call_tool("esp_efuse_read", {
    "port": "/dev/ttyUSB0"
})

result = await client.call_tool("esp_efuse_read", {
    "port": "/dev/ttyUSB0",
    "efuse_name": "MAC"
})

Return Value

Full summary:

{
  "success": true,
  "port": "/dev/ttyUSB0",
  "efuses": {
    "MAC": "aa:bb:cc:dd:ee:ff",
    "FLASH_CRYPT_CNT": "0",
    "ABS_DONE_0": "0",
    "JTAG_DISABLE": "0",
    "ADC_VREF": "1100"
  },
  "raw_output": "EFUSE_NAME (BLOCK0) Description = value R/W (hex)\n..."
}

Specific eFuse:

{
  "success": true,
  "port": "/dev/ttyUSB0",
  "efuse_name": "MAC",
  "value": "aa:bb:cc:dd:ee:ff"
}

When a requested eFuse is not found, the response includes the list of available names:

{
  "success": false,
  "error": "eFuse 'NONEXISTENT' not found",
  "available_efuses": ["MAC", "FLASH_CRYPT_CNT", "ABS_DONE_0", "..."],
  "port": "/dev/ttyUSB0"
}

esp_efuse_burn

Permanently program an eFuse bit field on the device. This operation is irreversible on real hardware. The tool reads the eFuse value before and after the burn to confirm the change.

Uses espefuse burn-efuse with the --do-not-confirm flag because confirmation is handled at the MCP client level.

Parameters

Name	Type	Default	Description
`efuse_name`	`str`	(required)	Name of the eFuse to burn (e.g., `"JTAG_DISABLE"`).
`value`	`str`	(required)	Value to burn (e.g., `"1"`, `"0x1"`).
`port`	`str \| None`	`None`	Serial port or `socket://` URI. Required.

Common eFuses

Name	Effect
`JTAG_DISABLE`	Permanently disables JTAG debugging interface
`FLASH_CRYPT_CNT`	Enables flash encryption (odd bit count = encrypted)
`ABS_DONE_0`	Permanently enables Secure Boot v1
`DISABLE_DL_ENCRYPT`	Disables flash encryption in UART download mode
`DISABLE_DL_DECRYPT`	Disables flash decryption in UART download mode
`DISABLE_DL_CACHE`	Disables flash cache in UART download mode

Example

# Disable JTAG on a QEMU device (safe to test)
result = await client.call_tool("esp_efuse_burn", {
    "efuse_name": "JTAG_DISABLE",
    "value": "1",
    "port": "socket://localhost:5555"
})

Return Value

{
  "success": true,
  "port": "socket://localhost:5555",
  "efuse_name": "JTAG_DISABLE",
  "value_requested": "1",
  "value_before": "0",
  "value_after": "1",
  "warning": "eFuse burn is IRREVERSIBLE on real hardware"
}