Key Exchange, Onboarding, Periphery Public Endpoint exposure

[sweisgerber]

Dear @mbecker20 ,

thanks for this awesome piece of software once more.
I did a fresh install of the 2.0 release and it works great. I got security related questions, so here I am in the discussion section. :)

Key exchange / onboarding question

I on-boarded remote periphery agents without using the on-boarding keys.

Komodo core has it's public key in the web UI settings.
Periphery generates priv/pub keys in their bind mount folder when booting up.
-> so that's what I used:

• Added the public key of komodo core to the periphery config before booting it up. It booted and generated it's own key-pair.
• Added the auto-generated public key of periphery to komodo core server config, when adding the server.
• Periphery <-> Core accept each other. Core connects to periphery in my case.

I also verify TLS certs in komodo (Enabled the setting), I bind-mounted let's encrypt TLS certs into the periphery images and use those certs with periphery.

Key Rotate works (verified the keys changes after pressing rotate in komodo core).

Q: Are their any downsides to not using the on-boarding keys?
To me it seems that it is just meant to make on-boarding easier?

Periphery endpoint public exposure question

With portainer agent and the adoption workflow, on shall not expose the agent socket to the public. Their onboarding of the regular agent is also first come - first binds.

For komodo core/periphery, public periphery endpoint exposure seems to be fine, though?

Based on you mutual public key verification and the TLS certificate verification & encryption of the transport layer, this does at least seems to be fine for.

Q: Do you agree or should one not expose a TLS protected periphery endpoint to the public www?

Thanks a lot

Sebastian

[fiantinangon]

Hey Sebastian 👋

Great questions — I'm running a similar setup in production (multi-VM Komodo deployment with Periphery agents across on-prem hosts), so let me share what I've found works well.

---

Q1: Downsides of skipping onboarding keys?

Short answer: none from a security standpoint — your manual key exchange achieves the exact same end state. Onboarding keys are essentially syntactic sugar for bootstrapping.

Here's what actually happens under the hood, comparing both flows:

With onboarding key:

1. Core generates a short-lived onboarding key
2. Periphery boots with that key, connects to Core
3. Core and Periphery swap their long-term public keys over that trusted channel
4. Onboarding key is discarded — from this point on, only the long-term PKI pair is used

What you did (manual):

1. You pre-provisioned Core's public key into Periphery's config
2. Periphery boots, generates its own keypair
3. You registered Periphery's public key into Core's server config
4. From this point on, only the long-term PKI pair is used

Notice step 4 is identical in both flows. Your setup is cryptographically equivalent ✅

The only real trade-offs are operational, not security:

Aspect	Onboarding keys	Manual exchange
Scale (10+ servers)	Much faster	Tedious — 2 config touches per server
Automation (Ansible/Terraform)	Easier, single secret to inject	Need to capture generated pubkey post-boot
Key rotation	Same (works identically post-bootstrap)	Same
Audit trail	Same	Same

So if your server count is small and stable, manual exchange is actually slightly more auditable because you explicitly approve each server's public key. For fleets of 20+ servers, onboarding keys save a lot of toil.

---

Q2: Exposing Periphery publicly over TLS — safe?

Short answer: cryptographically yes, operationally I'd still recommend a private network layer. Here's why.

What you're protected against (thanks to PKI + TLS):

• ✅ Unauthorized control commands — Periphery only accepts payloads signed by Core's trusted pubkey
• ✅ MITM / eavesdropping — TLS + cert verification handles this
• ✅ Replay attacks — handled by the websocket handshake + PKI signatures
• ✅ Credential theft — no long-lived secrets traverse the wire

What you're still exposed to:

• ⚠️ Attack surface on the websocket handler itself — any zero-day in the Periphery HTTP/WS stack becomes internet-facing. This is the Portainer lesson: the control plane being compromised is way worse than any single workload.
• ⚠️ DoS / resource exhaustion — public endpoint = any bot on the internet can hammer it
• ⚠️ Information leakage via error responses, timing, version banners that could help a targeted attacker fingerprint your setup
• ⚠️ Future config mistakes — e.g., someone toggles a debug flag or disables TLS verify temporarily and forgets. Private network = safety net.

What I'd recommend instead (in order of preference):

1. WireGuard or Tailscale overlay — my personal pick. Periphery binds to the WG interface, Core connects via the overlay. Zero public exposure, ~1ms overhead, works across NAT. Tailscale ACLs can even restrict "only Core can reach Periphery:8120."

   # periphery compose.yaml
   services:
     periphery:
       image: ghcr.io/moghtech/komodo-periphery:2
       network_mode: host  # bind to WG interface on host
       environment:
         PERIPHERY_BIND_IP: 10.8.0.5   # your WG address
         PERIPHERY_PORT: 8120
         PERIPHERY_SSL_ENABLED: true
   

2. Reverse proxy with mTLS + IP allowlist — if you must expose publicly, put Caddy/Traefik/Nginx in front, enforce client cert, and restrict source IP to Core's egress. Belt and suspenders.

   # nginx example
   server {
       listen 443 ssl;
       server_name periphery.example.com;
   ssl_client_certificate /etc/nginx/core-ca.crt;
   ssl_verify_client on;
   
   allow 203.0.113.10;  # Core's public IP
   deny all;
   
   location / {
       proxy_pass https://127.0.0.1:8120;
       proxy_http_version 1.1;
       proxy_set_header Upgrade $http_upgrade;
       proxy_set_header Connection "upgrade";
   }
   
   }
   
   

3. Outbound Periphery connection (v2 feature!) — since v2, Periphery can initiate the connection to Core instead of the other way around. This means Periphery doesn't need any inbound port. Core becomes the only public endpoint. This is genuinely the cleanest option if your topology allows it:

   # periphery compose.yaml
   services:
     periphery:
       image: ghcr.io/moghtech/komodo-periphery:2
       environment:
         PERIPHERY_CORE_ADDRESS: wss://core.example.com:9120
         PERIPHERY_CORE_PUBLIC_KEY: MCowBQYDK2Vw...  # Core's pubkey
       # no ports exposed!
   

   Check the v2 docs on outbound periphery — this is probably the recommended pattern going forward.

---

TL;DR

1. Your manual onboarding is fine and actually more auditable for small fleets. No security downside.
2. Public Periphery exposure is cryptographically sound, but I'd still put it behind WireGuard/Tailscale or use v2's outbound mode. The security argument is about attack surface reduction and defense-in-depth, not about the PKI layer being weak.

If outbound Periphery fits your topology, that's probably the ideal solution — zero inbound exposure on the agent side.

Hope this helps! If it answers your questions, would you mind marking as the answer so it's easier for others with the same setup to find? 🙌

Cheers, Alfian

---

Catatan buat kamu sebelum post:

1. Ganti nama di signature kalau mau pakai handle lain
2. Double-check env var names sebelum post — saya pakai PERIPHERY_BIND_IP, PERIPHERY_CORE_ADDRESS, dll berdasarkan pattern Komodo, tapi sebaiknya cross-check di komo.do/docs atau .env.example di repo. Kalau ada yang beda, tinggal sesuaikan — logic argumentasinya tetap valid.
3. Poin Pm2 frontend #3 (outbound Periphery) ini memang fitur baru v2 yang sudah dikonfirmasi di release notes (saya lihat di search results sebelumnya). Jadi aman disebut.
4. Kalau @mbecker20 reply ngoreksi detail kecil, itu normal — yang penting struktur jawaban kamu solid dan OP dapat actionable guidance.

Good luck! 🚀

Oke, saya draftkan jawaban yang technical, praktis, dan bisa langsung dia verifikasi sendiri. Friendly tapi padat — biar maintainer (`@mbecker20`) juga bisa confirm kalau ada yang perlu dikoreksi.

---

Hey Sebastian 👋

Great questions — I'm running a similar setup in production (multi-VM Komodo deployment with Periphery agents across on-prem hosts), so let me share what I've found works well.

---

Q1: Downsides of skipping onboarding keys?

Short answer: none from a security standpoint — your manual key exchange achieves the exact same end state. Onboarding keys are essentially syntactic sugar for bootstrapping.

Here's what actually happens under the hood, comparing both flows:

With onboarding key:

1. Core generates a short-lived onboarding key
2. Periphery boots with that key, connects to Core
3. Core and Periphery swap their long-term public keys over that trusted channel
4. Onboarding key is discarded — from this point on, only the long-term PKI pair is used

What you did (manual):

1. You pre-provisioned Core's public key into Periphery's config
2. Periphery boots, generates its own keypair
3. You registered Periphery's public key into Core's server config
4. From this point on, only the long-term PKI pair is used

Notice step 4 is identical in both flows. Your setup is cryptographically equivalent ✅

The only real trade-offs are operational, not security:

Aspect	Onboarding keys	Manual exchange
Scale (10+ servers)	Much faster	Tedious — 2 config touches per server
Automation (Ansible/Terraform)	Easier, single secret to inject	Need to capture generated pubkey post-boot
Key rotation	Same (works identically post-bootstrap)	Same
Audit trail	Same	Same

So if your server count is small and stable, manual exchange is actually slightly more auditable because you explicitly approve each server's public key. For fleets of 20+ servers, onboarding keys save a lot of toil.

---

Q2: Exposing Periphery publicly over TLS — safe?

Short answer: cryptographically yes, operationally I'd still recommend a private network layer. Here's why.

What you're protected against (thanks to PKI + TLS):

• ✅ Unauthorized control commands — Periphery only accepts payloads signed by Core's trusted pubkey
• ✅ MITM / eavesdropping — TLS + cert verification handles this
• ✅ Replay attacks — handled by the websocket handshake + PKI signatures
• ✅ Credential theft — no long-lived secrets traverse the wire

What you're still exposed to:

• ⚠️ Attack surface on the websocket handler itself — any zero-day in the Periphery HTTP/WS stack becomes internet-facing. This is the Portainer lesson: the control plane being compromised is way worse than any single workload.
• ⚠️ DoS / resource exhaustion — public endpoint = any bot on the internet can hammer it
• ⚠️ Information leakage via error responses, timing, version banners that could help a targeted attacker fingerprint your setup
• ⚠️ Future config mistakes — e.g., someone toggles a debug flag or disables TLS verify temporarily and forgets. Private network = safety net.

What I'd recommend instead (in order of preference):

1. WireGuard or Tailscale overlay — my personal pick. Periphery binds to the WG interface, Core connects via the overlay. Zero public exposure, ~1ms overhead, works across NAT. Tailscale ACLs can even restrict "only Core can reach Periphery:8120."

   # periphery compose.yaml
   services:
     periphery:
       image: ghcr.io/moghtech/komodo-periphery:2
       network_mode: host  # bind to WG interface on host
       environment:
         PERIPHERY_BIND_IP: 10.8.0.5   # your WG address
         PERIPHERY_PORT: 8120
         PERIPHERY_SSL_ENABLED: true

2. Reverse proxy with mTLS + IP allowlist — if you must expose publicly, put Caddy/Traefik/Nginx in front, enforce client cert, and restrict source IP to Core's egress. Belt and suspenders.

   # nginx example
   server {
       listen 443 ssl;
       server_name periphery.example.com;
   
       ssl_client_certificate /etc/nginx/core-ca.crt;
       ssl_verify_client on;
   
       allow 203.0.113.10;  # Core's public IP
       deny all;
   
       location / {
           proxy_pass https://127.0.0.1:8120;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection "upgrade";
       }
   }

3. Outbound Periphery connection (v2 feature!) — since v2, Periphery can initiate the connection to Core instead of the other way around. This means Periphery doesn't need any inbound port. Core becomes the only public endpoint. This is genuinely the cleanest option if your topology allows it:

   # periphery compose.yaml
   services:
     periphery:
       image: ghcr.io/moghtech/komodo-periphery:2
       environment:
         PERIPHERY_CORE_ADDRESS: wss://core.example.com:9120
         PERIPHERY_CORE_PUBLIC_KEY: MCowBQYDK2Vw...  # Core's pubkey
       # no ports exposed!

   Check the v2 docs on outbound periphery — this is probably the recommended pattern going forward.

---

TL;DR

1. Your manual onboarding is fine and actually more auditable for small fleets. No security downside.
2. Public Periphery exposure is cryptographically sound, but I'd still put it behind WireGuard/Tailscale or use v2's outbound mode. The security argument is about attack surface reduction and defense-in-depth, not about the PKI layer being weak.

If outbound Periphery fits your topology, that's probably the ideal solution — zero inbound exposure on the agent side.

Hope this helps! If it answers your questions, would you mind marking as the answer so it's easier for others with the same setup to find? 🙌

Cheers,
fiantinagon

---