# MITRE EMB3D

[![Documentation build status](https://readthedocs.org/projects/mitre-emb3d/badge/?version=latest
)](https://mitre-emb3d.readthedocs.io/en/latest/)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)


A CLI, MCP Server, & AI based Threat Analysis for https://emb3d.mitre.org/

## Run

### Via `uvx`

```bash
uvx mitre-emb3d --help
uvx mitre-emb3d --pprint properties Networking --level 3
```

## Add to your project

The project can be used both as a tool & library

```bash
uv add mitre-emb3d
```


## What this project enables!!

### AI Driven Embedded Project Threat Analysis

* Determine which device properties are applicable to your project
* Do threat analysis
* Generate a detailed project report and heatmap

```bash
uvx mitre-emb3d ai --repo <path-to-repo> --config config.toml map-properties
uvx mitre-emb3d ai --repo <path-to-repo> --config config.toml threat-analysis
uvx mitre-emb3d ai --repo <path-to-repo> --config config.toml gen-site
```

See the documentation & guides for more information on configuration
https://mitre-emb3d.readthedocs.io/en/latest/guides/

### CLI & MCP Server

You can use the CLI or MCP server or both to build your own solutions

* List device properties for a given category
* List threats for a given category
* List threats for a given device property
* List device properties for a certain threat
* List mitigations for a given threat
* Get detailed information about a threat
* Get detailed information about a mitigation
* A CLI - AI Agent first (returns JSON output) / For humans add `--pprint` to see beautiful ouput
* An MCP Server

Example -

```bash
$ uvx mitre-emb3d --pprint list-threats-for-category "Networking"
- TID-221: Authentication Bypass By Message Replay
- TID-222: Critical System Service May Be Disabled
- TID-310: Remotely Accessible Unauthenticated Services
- TID-316: Incorrect Certificate Verification Allows Authentication Bypass
- TID-317: Predictable Cryptographic Key
- TID-318: Insecure Cryptographic Implementation
- TID-401: Undocumented Protocol Features
- TID-404: Remotely Triggerable Deadlock/DoS
- TID-405: Network Stack Resource Exhaustion
- TID-406: Unauthorized Messages or Connections
- TID-407: Missing Message Replay Protection
- TID-408: Unencrypted Sensitive Data Communication
- TID-410: Cryptographic Protocol Side Channel
- TID-411: Weak/Insecure Cryptographic Protocol
- TID-412: Network Routing Capability Abuse
```

> Note --pprint (default is OFF, default output is JSON) for display


***Explore other commands using the CLI help***

```markdown

 Usage: mitre-emb3d [OPTIONS] COMMAND [ARGS]...

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --version                                      Show the version of CLI and exit                                                                                              │
│ --release                                TEXT  2.0.1, 2.0 ... [default: 2.0.1]                                                                                               │
│ --loglevel            -l                 TEXT  Set the logging level (debug, info, warning, error, critical) [default: warning]                                              │
│ --pprint                  --no-pprint          Whether to pretty-print the output (e.g. JSON lists) [default: no-pprint]                                                     │
│ --install-completion                           Install completion for the current shell.                                                                                     │
│ --show-completion                              Show completion for the current shell, to copy it or customize the installation.                                              │
│ --help                                         Show this message and exit.                                                                                                   │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ list-categories               List the categories                                                                                                                            │
│ list-properties-for-category  List properties for a certain category                                                                                                         │
│ list-properties-for-threat    List properties for a certain threat                                                                                                           │
│ list-threats-for-category     List threats for a certain category                                                                                                            │
│ list-threats-for-property     List threats for a certain device property                                                                                                     │
│ list-mitigations              List mitigations for a certain threat                                                                                                          │
│ threat                        Threat Information                                                                                                                             │
│ mitigation                    Mitigation Information                                                                                                                         │
│ mcp                           Launch the MCP server                                                                                                                          │
│ ai                            AI related commands                                                                                                                            │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

```

## MCP Server

> At the moment only STDIO is supported

For your `mcp.json` add the server like this

```json
{
  "servers": {
    "mitre-emb3d": {
      "command": "uvx",
      "args": ["mitre-emb3d", "mcp"]
    }
  }
}

```

Use mcp inspector to play with the MCP Server

```bash
npx -y @modelcontextprotocol/inspector uvx mitre-emb3d mcp
```
