YggdraSIM

July 2, 2026 · View on GitHub

YggdraSIM is a Python toolkit for secure-element research, eUICC analysis, SIM/eSIM management, OTA payload work, SCP11 relay/local flows, and SAIP profile-package tooling. The repository keeps the operator surfaces, protocol helpers, and test suite in one workspace so card work, relay work, and package work can be exercised without switching projects. The SAIP decoding path and the SCP11 local / eIM flows pull in upstream pySim; install them in one shot with pip install -e '.[saip]' (the [saip] extra pins pySim directly from its GitHub mirror).

Releases. v1.0.1 was tagged on 2026-06-05 for SCP11 notification recovery fixes on the v1 line. Check out the frozen v1.0.0 footprint with git checkout v1.0.0. The main branch carries in-flight v2 work — surfaces tagged (post-v1 staging) below are part of that v2 line and are not covered by the v1.0.x compatibility promise. See CHANGELOG.md for release notes and the active backlog.

Distribution at a glance

YggdraSIM is offered in three shapes:

Flavor	Platforms	Card Bridge / remote APDU	Direct SIMtrace2 HIL	Guide
Clean executable	Windows / macOS / Linux x86_64 / Raspberry Pi (arm64)	Yes	No	`guides/INSTALL_CLEAN.md`
Full executable	Linux x86_64 / Raspberry Pi (arm64)	Yes	Yes	`guides/INSTALL_FULL.md`
Source checkout (`pip install -e .`)	Any OS, direct HIL opt-in on Linux	Yes	Linux only	`guides/INSTALL_FROM_SOURCE.md`

The clean flavor is the default distribution. It ships Card Bridge and remote APDU streaming on Windows, macOS, Linux, and Raspberry Pi, but omits the local SIMtrace2/RemSIM HIL runtime and therefore does not require pyudev or osmo-remsim-client-st2. Use the full flavor when the same machine must drive a SIMtrace2 directly, or install from source when you want the test suite, editable imports, or on-device builds. HIL operators should also read guides/SIMTRACE2_CARDEM_GUIDE.md for flashing and updating the SIMtrace2 firmware. Raspberry Pi users have a dedicated walk-through in guides/INSTALL_RASPBERRYPI.md.

Every launcher reports its active flavor in the main-menu banner, the --version string, and the --doctor report, so operators can always tell which bundle they are working with.

Scripted install

One-liner installer scripts live in scripts/install/ and wrap both the pre-built-release and the editable-source paths for every supported host. See scripts/install/README.md for the full flag reference.

scripts/install/install-linux.sh                      # Linux desktop, clean, latest release
scripts/install/install-linux.sh --flavor full        # Linux desktop, HIL-capable release
scripts/install/install-macos.sh                      # macOS (clean only)
scripts/install/install-raspberrypi.sh --flavor full  # Pi arm64, HIL-capable

powershell -ExecutionPolicy Bypass -File scripts\install\install-windows.ps1

Ownership and authors

Copyright holder: 1oT OÜ (Tallinn, Estonia)
Author and lead maintainer: Hampus Hellsberg (Creator, Lead Architect, Lead Maintainer)
Additional contributors: see repository commit history

What YggdraSIM contains

Subsystem	Role	Primary operator surface
`main/`	Unified launcher, path setup, and in-process module dispatch	`python main/main.py`
`SCP03/`	GlobalPlatform-style admin shell, filesystem work, GSMA retrieval, report/export	interactive shell + one-shot commands
`SCP80/`	OTA packet construction, decode, and reader/send flows	OTA CLI
`SCP11/live/`	eSIM management relay shell for LPAd / IPAd work	interactive SCP11 console
`SCP11/test/`	Compatibility namespace for older imports	import compatibility only
`SCP11/local_access/`	Direct local `ISD-R` bring-up and one-shot `LOAD-PROFILE`	local SCP11 shell
`SCP11/eim_local/`	eIM-local package generation, hotfolder queues, handover flows, and response tracking	eIM local shell
`SIMCARD/`	In-process simulated UICC / eUICC: ETSI TS 102 221 file system, GP / SCP03 / SCP80, ISD-R + ISD-Ps, ETSI TS 102 223 toolkit + BIP, Milenage / TUAK AKA, 5G AKA / AKMA / SUCI / GET IDENTITY	selected via `--card-backend sim`
`Tools/HilBridge/`	SIMtrace2-based hardware-in-the-loop bridge: RSPRO relay, RemSIM lifecycle, GSMTAP mirror, remote-card input, offline pcap review, AT+CSIM/CRSM transcoding (`at_simlink`)	`yggdrasim-hil-bridge` (Linux)
`Tools/ProfilePackage/`	SAIP shell, transcode UI, lint engine, JSON↔DER bridge	profile-package shell + TUI
`Tools/SuciTool/`	SUCI helper tooling	helper shell
`Tools/Asn1TlvDecode/`	BER/DER ASN.1, BER-TLV, and APDU decode helper	`yggdrasim-asn1` or `python main/main.py --asn1`
`Tools/ApduFuzz/`	Safety-gated eUICC APDU mutation fuzzer (`--i-mean-it` + ICCID/IMSI allow-list)	`yggdrasim-apdu-fuzzer`
`Tools/EumDiag/`	EUM / SM-DP+ "God-Mode": session-key injection + Wireshark/tshark Lua dissector for BF36 BPPs	`yggdrasim-eum-diag`
`Tools/YggdraCore/` (post-v1 staging)	In-process 5G core stubs (AUSF / AAnF) for AKA / AKMA flows + BYO-Open5GS provisioning bridge	FastAPI loopback (opt-in via `YGGDRASIM_5GCORE_MODE=stub`)
`Tools/CardBridge/` (post-v1 staging)	Loopback HTTP APDU bridge for streaming a PC/SC reader to another host over SSH	`python -m Tools.CardBridge`
`yggdrasim_common/gui_server/`	Optional Universal GUI Command Center: FastAPI API + pywebview desktop window or headless lab server, live APDU dock, remote-rig controls	`--gui` / `--web-server`
`plugins/`	Runtime-loaded optional private extensions discovered only after explicit opt-in	drop-in `register_plugins()` modules
`pysim/`	Optional developer checkout of upstream pySim (gitignored). Only needed when working against an unreleased upstream branch; the released SAIP surface ships via the `[saip]` extra (`pip install 'yggdrasim[saip]'`).	optional external tree

Core capabilities

PC/SC-based GlobalPlatform and UICC/eUICC administration through SCP03.
OTA packet generation, wrapping, transport, and decode through SCP80.
Single SCP11 eSIM management relay for live and lab work, with SCP11/relay and SCP11/test retained as compatibility namespaces.
Direct local SCP11 provisioning and metadata handling through SCP11/local_access.
eIM-centric local package work, hotfolder campaigns, handover validation, and response tracking through SCP11/eim_local.
Hardware-in-the-loop SIMtrace2 bridge with RemSIM lifecycle, GSMTAP mirroring, brokered APDU side-channel access, remote-card input, and AT+CSIM / AT+CRSM transcoding for modem cold-boot rigs through Tools/HilBridge.
In-process simulated UICC / eUICC backend (--card-backend sim) with full ETSI TS 102 221 file system, ISD-R + ISD-P personalities, persistent EID-scoped store, GP / SCP03 / SCP80 secure messaging, and an ETSI TS 102 223 toolkit + BIP runtime.
3GPP TS 33.501 5G AKA, EAP-AKA' (TS 33.402), AKMA (TS 33.535), and SUPI / SUCI Profile A & B (TS 33.501 §C.3) on the simulated card, including TS 31.102 §7.1.2.4 GET IDENTITY (P2 = 0x01 SUCI calculation). (SIMCARD layer shipped in v1.0.0.)
In-process 5G-core stubs for end-to-end AKA + AKMA loops (Tools/YggdraCore: AUSF, AAnF, subscription store, optional FastAPI loopback) plus a BYO-Open5GS provisioning bridge for hosts that already run a real 5GC. (post-v1 staging on main; documentation, CLI surface, and HTTP-loopback hardening not part of this release — see CHANGELOG.md.)
SAIP / UPP profile inspection, linting, JSON↔DER transcode, and shell automation through Tools/ProfilePackage.
Visual side-by-side SAIP profile diffing (shell + Textual TUI) via DIFF / DIFF-TUI inside the profile-package shell.
Simulator-to-TUI auto-open pipeline via yggdrasim-profile-autoload and the WATCH-SIMCARD shell command.
Opt-in, safety-gated eUICC APDU mutation fuzzer via yggdrasim-apdu-fuzzer (--i-mean-it + ICCID/IMSI allow-list required).
EUM / SM-DP+ diagnostics "God-Mode": session-key injection and Wireshark/tshark Lua dissector for BF36 Bound Profile Packages via yggdrasim-eum-diag.
Optional Universal GUI Command Center (--gui desktop / --web-server remote-lab) with reader selection, action forms, Card Bridge controls, and a live APDU dock fed by a process-wide recorder.
Centralized mutable state in SQLite, with optional gpg-based encryption for sensitive payloads.

Quick start

Prerequisites

Python 3.10+
A PC/SC-compatible smart-card reader for card flows
Optional: gpg when encrypted SQLite inventory payloads are enabled

Install Python dependencies

python -m pip install -r requirements.txt
python -m pip install -e '.[saip]'

The [saip] extra installs upstream pySim from its GitHub mirror (pySim @ git+https://github.com/osmocom/pysim.git). That gives you the SCP11-local flows, eIM-local flows, SAIP ASN.1 compile, the SAIP transcode TUI, and the profile-scaffold wizards without any manual clone step. A bare pip install -e . without the extra still works if you only need the flows that do not touch SAIP (core SIMCARD simulator, HIL bridge, SCP03, SCP80, SCP11 relay); yggdrasim --doctor marks pySim as WARN in that case, which is expected.

If you are working against an unreleased upstream pySim branch you can still drop a developer checkout at <repo>/pysim (git clone https://github.com/osmocom/pysim.git pysim); that tree takes priority over the installed wheel. The pysim/ path stays gitignored so it never ships in the distribution.

The editable install is what makes python -m SCP11.live, python -m SCP11.local_access, and the other package entry points work from any directory in the same environment. Without it, those python -m ... commands only work when the repository root is already on sys.path, such as when you are inside the repo.

The editable install also provides installed commands:

yggdrasim
yggdrasim-cli
yggdrasim-gui
yggdrasim-web-server
yggdrasim-scp03
yggdrasim-scp80
yggdrasim-scp11
yggdrasim-scp11-live
yggdrasim-scp11-relay
yggdrasim-scp11-local-access
yggdrasim-scp11-eim-local
yggdrasim-hil-bridge
yggdrasim-hil-supervisor
yggdrasim-profile-package
yggdrasim-profile-autoload
yggdrasim-apdu-fuzzer
yggdrasim-eum-diag
yggdrasim-suci-tool
yggdrasim-asn1

Docker and bundle packaging

Container, PyInstaller, .deb, and .exe notes now live in:

guides/BUILD_AND_PACKAGING.md — flavor-aware build commands
guides/INSTALL_CLEAN.md — operator install for the clean bundle
guides/INSTALL_FULL.md — operator install for the HIL-capable bundle
guides/INSTALL_FROM_SOURCE.md — editable install and test-suite usage

Quick container smoke path:

docker build -t yggdrasim:clean .
docker run --rm -it yggdrasim:clean yggdrasim-scp11 --cmd "HELP; EXIT"

# HIL-capable image (Linux hosts only; SIMtrace2 access requires USB passthrough)
docker build --build-arg YGGDRASIM_FLAVOR=full -t yggdrasim:full .

python main/main.py
python main/main.py --debug
python main/main.py --card-backend sim --sim-eim-identity /path/to/card_side_eim_identity.json

Use --debug (or --verbose) on the wrapper when you want debug to become the global default for modules launched from the main menu. Without it, module-specific debug flags remain opt-in.

Diagnostic helpers:

python main/main.py --version
python main/main.py --doctor

Optional Universal GUI Command Center (requires the gui or gui-server extra):

pip install -e '.[gui]'
yggdrasim-gui                                      # FastAPI on loopback + native pywebview window
yggdrasim-web-server --token-file ./tok            # remote-lab API, bearer-token mandatory

The CLI still supports yggdrasim --gui and yggdrasim --web-server; the dedicated commands are the clearer operator path when both CLI and GUI executables are installed. The GUI is intentionally off by default; neither mode imports FastAPI / uvicorn / pywebview until selected, so the baseline install stays lean. See guides/GUI_HOST_SHELL_GUIDE.md for the operator surface.

--version is sourced from pyproject.toml through yggdrasim_common/__about__.py, so any wrapper, plugin, or installed command that imports yggdrasim_common.__about__.__version__ reports the same value. --doctor runs a read-only preflight report covering Python version, cryptography, pycryptodomex, asn1tools, the optional pysim/ tree, SQLite, optional textual (TUI), PC/SC reader visibility, and the gpg binary used by the optional inventory encryption provider. Exit code is 0 when every probe is ok/info and 1 when any probe is warn/fail, so the helper can be used directly from CI pipelines.

Simulator note:

--sim-eim-identity selects the simulated card's default BF55 eIM identity file.
Workspace/LocalEIM/eim_identity.json remains the Local eIM shell identity and does not automatically reconfigure the simulated card.

Direct module entry points

After python -m pip install -e /path/to/YggdraSIM, these can be run from any directory that uses the same Python environment:

python -m SCP03
python -m SCP80
python -m SCP11
python -m SCP11.live
python -m SCP11.relay
python -m SCP11.local_access
python -m SCP11.eim_local
python -m Tools.HilBridge.main
python -m Tools.HilBridge.supervisor
python -m Tools.ProfilePackage
python -m Tools.SuciTool
python -m Tools.Asn1TlvDecode

If you skip the editable install, run them from the repository root instead.

Installed command equivalents after editable install:

yggdrasim
yggdrasim-cli
yggdrasim-gui
yggdrasim-web-server
yggdrasim-scp03
yggdrasim-scp80
yggdrasim-scp11
yggdrasim-scp11-live
yggdrasim-scp11-relay
yggdrasim-scp11-local-access
yggdrasim-scp11-eim-local
yggdrasim-hil-bridge
yggdrasim-hil-supervisor
yggdrasim-profile-package
yggdrasim-profile-autoload
yggdrasim-apdu-fuzzer
yggdrasim-eum-diag
yggdrasim-suci-tool
yggdrasim-asn1

For non-interactive automation, piping, and ready-to-run profile lifecycle examples, see:

guides/CLI_AND_PIPING_GUIDE.md
guides/PROFILE_LIFECYCLE_CLI_CHEATSHEET.md
guides/BUILD_AND_PACKAGING.md
guides/HIL_BRIDGE_GUIDE.md
guides/INSTALL_CLEAN.md
guides/INSTALL_FULL.md
guides/INSTALL_FROM_SOURCE.md
guides/INSTALL_RASPBERRYPI.md
guides/SIMTRACE2_CARDEM_GUIDE.md

Persistent state and security model

YggdraSIM now uses state/device_inventory.sqlite3 as the primary mutable state store for:

per-card ICCID inventory payloads
per-card EID inventory payloads
per-eIM identity counters and runtime markers
module-level mutable settings such as the migrated SCP03 and SCP80 runtime state

Current migration model:

Workspace/SCP03/keys.ini is a legacy import source. Live SCP03 state is now SQLite-primary.
SCP80/ota_config.ini is a legacy import source. Live SCP80 state is now SQLite-primary.
Workspace/LocalEIM/eim_runtime_state.json is a legacy import source. Live runtime state is now SQLite-primary.
Workspace/LocalEIM/eim_identity.json defines the Local eIM shell identity, endpoint defaults, and certificate paths.
Workspace/SCP03/aid.txt, Workspace/SCP03/fids.txt, and Workspace/SCP03/binds.json remain plain files because they are still better suited to manual editing and diff review.
Workspace/SIMCARD/eim_identity.json controls the simulator's default BF55 eIM identity and is intentionally separate from Workspace/LocalEIM/eim_identity.json.
use Workspace/SIMCARD/isdr_config.json with eim_entries when you need a full custom card-side eIM layout instead of the single seeded simulator default

Optional encryption:

state/inventory_crypto.json controls SQLite payload encryption.
Default is enabled: false to keep onboarding friction low.
When enabled, inventory and module-state payloads are encrypted on write and decrypted only on demand.
Current provider is gpg via the system binary and agent/keyring model.

Frozen executable runtime model:

source runs continue to use the repository tree directly
frozen builds spawn a writable runtime tree under YggdraSIM-data next to the executable when possible
if that location is not writable, the runtime tree falls back to ~/YggdraSIM-data
set YGGDRASIM_RUNTIME_ROOT to force a specific runtime root
user-editable certs, keys, package templates, hotfolders, caches, and state are read from that writable runtime tree in frozen mode
when YGGDRASIM_ALLOW_PLUGINS=1 is set, plugins/ is scanned at launch from the writable runtime root so optional capabilities can be dropped in after publication without rebuilding the core

Optional plugins

YggdraSIM supports runtime plugins through plugins/.

the loader scans plugins/ at launch only when YGGDRASIM_ALLOW_PLUGINS=1 is set and registers plugin-provided capabilities
the folder is intended for optional or restricted features that should not be shipped in the published core
plugin implementation files are ignored by default; keep the loader contract and drop local plugins into plugins/ when needed
see plugins/README.md for the expected register_plugins(manager) entry point

Typical operator paths

SCP03 admin shell

Use SCP03 for:

GlobalPlatform authentication and registry operations
ETSI / 3GPP filesystem navigation
GSMA retrieval and local profile-state work
report/export generation
HIL keybag export via EXPORT-KEYBAG (after AUTH-SD)

Example:

[APDU] > AUTH-SD
[A0...00] > APPS
[A0...00] > LIST
[A0...00] > SELECT USIM/IMSI
[A0...00] > READ
[A0...00] > EXPORT-KEYBAG session.keys.json run-01

SCP80 OTA shell

Use SCP80 for:

OTA payload wrapping
secured packet field tuning
direct reader-mode or print-only flows
ICCID-specific OTA state reuse through the shared inventory

SCP11 eSIM management relay

Use SCP11/live for:

LPAd: DOWNLOAD-PROFILE <activation>
IPAd: DISCOVER, DOWNLOAD [matchingId]

Example:

[eSIM Management] > HELP
[eSIM Management] > DISCOVER
[eSIM Management] > DOWNLOAD-PROFILE LPA:1$...

See:

SCP11/README.md
SCP11/live/README.md
guides/PROFILE_LIFECYCLE_CLI_CHEATSHEET.md

HIL bridge and SIMtrace2

Use Tools/HilBridge when you need a physical-card-to-modem bridge with:

RSPRO / osmo-remsim-client-st2 connectivity on 127.0.0.1:9997
optional remote-card input through Tools.CardBridge and SSH
GSMTAP mirroring to Wireshark on UDP 4729
exclusive reader ownership with relay-backed YggdraSIM side access
manual HIL capture sessions started and stopped on demand
offline review of saved .pcap / .pcapng captures via python main/main.py --open-pcap <path> (no bridge, no supervisor); optional --keybag <path> unwraps SCP03 / SCP11c secure-messaging APDUs inline

Session-key keybag JSONs are produced by:

EXPORT-KEYBAG in the SCP03 admin shell (after AUTH-SD)
EXPORT-KEYBAG in SCP11.local_access (after any BSP-building verb)
python -m SCP11.local_access --dump-keybag <path> non-interactively

python -m SCP11.live --dump-keybag is a documented no-op stub — live SCP11c BSP keys are derived inside the eUICC and never reach the host.

The local SIMtrace2/RemSIM HIL bridge is only shipped in the full executable and in source checkouts on Linux. The clean executable still ships Card Bridge / remote APDU streaming for Windows, macOS, Linux, and Raspberry Pi; it hides the [B] Local SIMtrace2 HIL Bridge Session menu entry and prints a pointer to the install guides when the entry is invoked manually.

See:

guides/HIL_BRIDGE_GUIDE.md — operator flow
guides/CARD_BRIDGE_GUIDE.md — remote reader and remote-rig APDU streaming
guides/INSTALL_FULL.md — HIL-capable executable install
guides/SIMTRACE2_CARDEM_GUIDE.md — flashing / updating SIMtrace2 and osmo-remsim-client-st2
guides/systemd/yggdrasim-hil-supervisor.service.example

Local SMDPP

Use SCP11/local_access for direct on-card local provisioning without the relay shells:

[Local SMDPP] > STATUS
[Local SMDPP] > PROFILE /path/to/profile.der
[Local SMDPP] > METADATA /path/to/metadata.json
[Local SMDPP] > LOAD-PROFILE
[Local SMDPP] > EXPORT-KEYBAG session.keys.json local-run

EXPORT-KEYBAG (or the non-interactive --dump-keybag <path> launcher flag) dumps the last-derived SCP11c BSP keys as a HIL keybag JSON for later offline decryption in the HIL decoded-APDU TUI.

This path now restores per-card local choices by EID from the shared SQLite inventory.

For --cmd, --stdin, and log-capture examples, use guides/PROFILE_LIFECYCLE_CLI_CHEATSHEET.md.

Local eIM

Use SCP11/eim_local when you need:

eIM identity and package fixtures
local handover simulation
hotfolder package exercises
AddInitialEim / AddEim command generation
eIM response logs and counter control

When the card side is simulated:

Workspace/LocalEIM/eim_identity.json still describes the local eIM / SM-DP+ side
Workspace/SIMCARD/eim_identity.json, the wrapper settings screen, or --sim-eim-identity controls what the simulated card advertises in BF55

See:

SCP11/eim_local/README.md
SCP11/eim_local/GUIDE.md
guides/PROFILE_LIFECYCLE_CLI_CHEATSHEET.md

Profile package tooling

Use Tools/ProfilePackage for:

SAIP shell operations
JSON↔DER transcode
linting and package inspection
saip-tool bridge work

The transcode UI now uses a configurable transcode output directory, persists its pane layout in the workspace, supports OS clipboard copy/paste, and writes *.transcode.json, *.transcode.der, and *.transcode.txt sidecars.

akaParameter tooling (3GPP TS 35.206 / TS 35.231):

LIST-AKA — read-only summary of every akaParameter PE in the active profile, including algorithm, Ki/OPc byte length, Keccak count, authCounterMax, and whether a 32-slot sqnInit seed is present.
PROVISION-AKA <out.der | IN-PLACE> [ALGORITHM=..] [KI=..] [OPC=..] [NUMBER-OF-KECCAK=..] [AUTH-COUNTER-MAX=..] [SQN-INIT=..] — tag-granular provisioning. With only an output path it walks the interactive wizard. Passing any NAME=VALUE override switches to non-interactive mode so the command is safe to paste into scripts or tests. IN-PLACE rewrites the currently-selected DER.
RANDOMIZE-AKA <out.der | IN-PLACE> [ALGORITHM=..] [INCLUDE-AUTH-COUNTER-MAX] [INCLUDE-SQN-INIT] — development helper that generates Ki / OPc / TOPc (and the TUAK-specific numberOfKeccak) via secrets.token_bytes and applies them to the first akaParameter PE. authCounterMax and sqnInit are skipped by default so replay-protection envelopes stay predictable.

Documentation map

site-docs/ - canonical mkdocs source tree. mkdocs serve -f mkdocs.yml renders it locally; site/ and site-oneot/ are generated mirrors and should not be edited by hand. For one concatenated Markdown file of the entire nav (offline reading or PDF export), run python3 site-docs/_tools/build_combined.py → root YggdraSIM.md (gitignored); see site-docs/_tools/README.md.
guides/README.md - index of authored operator and developer guides
guides/CAPABILITIES.md - suite-level capability reference grouped by subsystem and workflow
guides/ARCHITECTURE.md - system structure, interdependency matrix, state model, and flow charts
guides/CLI_AND_PIPING_GUIDE.md - shared non-interactive command and piping conventions
guides/PROFILE_LIFECYCLE_CLI_CHEATSHEET.md - ready-to-run lifecycle and logging command recipes
guides/DIAGNOSTICS_TOOLBOX.md - --doctor, capture, and inventory triage
guides/BUILD_AND_PACKAGING.md - Docker, PyInstaller, .deb, and packaging notes
guides/INSTALL_CLEAN.md - clean-flavor executable install (Win / macOS / Linux / Pi)
guides/INSTALL_FULL.md - HIL-capable full executable install (Linux)
guides/INSTALL_FROM_SOURCE.md - editable source install with extras matrix
guides/INSTALL_RASPBERRYPI.md - Raspberry Pi specific install notes
guides/SIMTRACE2_CARDEM_GUIDE.md - flashing / updating SIMtrace2 and the remsim toolchain
guides/HIL_BRIDGE_GUIDE.md - physical-card HIL bridge setup, supervision, and Wireshark usage
guides/CARD_BRIDGE_GUIDE.md - remote reader / APDU streaming setup over SSH
guides/TEMPLATE_AND_TOKENS.md - SAIP profile-template token reference
guides/systemd/yggdrasim-hil-supervisor.service.example - example systemd --user unit for the HIL supervisor
docs/ - vendor / standards reference workspace (GPC v2.3.1, SGP.02 / 22 / 32, ETSI TS 102 221 / 222 / 223 / 225 / 226, TS 31.102, RSPRO.asn, AKMA overview). The only schema the tool needs at runtime (RSPRO.asn) is redistributed inside Tools/HilBridge/RSPRO.asn as package data, so a fresh pip install yggdrasim works without a docs/ tree on disk. The folder is gitignored so the verbatim standards copies stay out of the published wheel; operators doing offline reference reading can populate docs/ themselves.
NOTICE - standards and third-party notice
AUTHORS - project attribution
CONTRIBUTING.md - contributor checklist (style, scope, sign-off)
SCP11/README.md - eSIM module selection and guide map
SCP11/live/README.md - eSIM management relay operator guide
SCP11/test/README.md - test compatibility namespace note
SCP11/local_access/README.md - local SCP11 shell guide
SCP11/eim_local/README.md - eIM module overview
SCP11/eim_local/GUIDE.md - detailed eIM operational guide
SCP11/relay/README.md - relay compatibility namespace note
SCP11/shared/README.md - shared SCP11 helper layer
plugins/README.md - runtime plugin contract and publication-ignore model
scripts/install/README.md - cross-platform one-liner installer flag reference

Repository layout

main/ - top-level launcher
yggdrasim_common/ - shared runtime: card-backend selection, registry, doctor, plugin runtime, GUI server, env-flag editor, APDU recorder
yggdrasim_common/registry.py - discoverable map of subsystems, entry points, and stable symbols
SCP03/ - admin shell, transport, controllers, decoders, reports
SCP80/ - OTA CLI, builder, transport, decode helpers
SCP11/ - relay, local, shared, and eIM-related flows
SIMCARD/ - in-process simulated UICC / eUICC backend (file system, AKA, GP, SCP03 / SCP80, toolkit, 5G AKA / AKMA / SUCI, GET IDENTITY)
Tools/HilBridge/ - SIMtrace2 bridge, supervisor, RemSIM lifecycle, GSMTAP mirror, remote-card input, AT+CSIM/CRSM transcoder
Tools/ProfilePackage/ - SAIP shell, linter, transcode UI
Tools/SuciTool/ - SUCI helper shell
Tools/ApduFuzz/ - eUICC APDU fuzzer
Tools/EumDiag/ - EUM / SM-DP+ diagnostics + tshark Lua dissector
Tools/YggdraCore/ - in-process AUSF / AAnF stubs, subscription store, BYO-Open5GS bridge (post-v1 staging)
Tools/CardBridge/ - loopback HTTP APDU bridge for streaming a PC/SC reader to another host over SSH (post-v1 staging)
plugins/ - runtime-loaded optional private extensions
tests/ - first-party test suite
state/ - shared SQLite inventory and crypto bootstrap config
pysim/ - optional developer checkout of upstream pySim (gitignored). The released SAIP surface installs via the [saip] extra (pip install 'yggdrasim[saip]'); this tree is only needed when you want to pin against an unreleased upstream branch.

Acknowledgements

A big-hearted thank you to the Osmocom community, the pySim maintainers and contributors, and Martin Paljak for GlobalPlatformPro. Their published tooling, interoperability references, and operator-focused ergonomics have materially improved the card, relay, and profile-package workflows that YggdraSIM builds on.

Scope notes

SCP03 is not a generic SCP11 provisioning shell. It is the admin / filesystem / retrieval environment.
SCP11/live is the primary relay-facing shell.
historical SCP11/experimental references are obsolete; relay work is now consolidated in SCP11/live, with compatibility namespaces under SCP11/relay and SCP11/test.
SCP11/local_access is the direct local SCP11 path against ISD-R.
SCP11/eim_local is the dedicated eIM-local package, hotfolder, response-tracking, and handover shell.
Compatibility helpers remain where card policy, certificate trust, or transport behavior can differ across eUICCs.

License and notice

License: GNU GPL v3.0
Notice: NOTICE