Back

A Zero-Trust Shell Built on Actors and Capabilities in AWK

uTelnetd: A Zero-Trust Shell Built on Actors and Capabilities in AWK

Inspired by a discussion with a community member about how nice it would be to have a lightweight shell running on an ESP32, I began developing uTelnetd. The initial concept was minimal—a telnet daemon. But as the implementation progressed, the vision expanded into an actor-based virtual filesystem with capability-based security.

Architecture Overview

Actor-Based Design: - Separate actors (e.g., fsManager, caps) run independently and communicate via named pipes (FIFOs). - Each actor manages its own state while interacting through a lightweight IPC protocol - This isolation ensures that each session can access the same resources in a distributed manner.

Capability System: - Tokens grant access to specific paths with defined permissions. They are implemented using a single letter codification for reading, writing, listing, changing directory, etc. - Ephemeral (6-char) tokens are short-lived, long-lived (24-char) tokens persist until revoked - Tokens can be derived hierarchically: child capabilities inherit parent scope and subset permissions

Virtual Filesystem: - Implemented entirely in AWK with two modes: direct (embedded data arrays) and central (actor-managed storage) - Currently includes operations for ls, touch, mkdir, rm, cp, cat, write - Planned additions include mv, rmdir, ln, and mount

NOTE: I initially resisted using session tokens. My primary reason was simply because that would make testing more challenging (as this is a test driven development project). For tests only, I decided to use a hardcoded seed for AWK’s pseudorandom generator. This makes it easy to anticipate what each token will be at every iteration. Also, the implementation of the ‘cap’ command in the interactive session makes tokens/caps extremely easy to create for users. All these reasons made me decide to go ahead with this method. If you want to try to use the project without the hassle of tokens, just use ‘sh ./telnet.sh 1’. It is what is used for testing.

Usage Example

# Start server locally
sh startServer.sh

# In a terminal: telnet localhost 9023

# Create a capability and mint a token
# rl are read and list accesses
# notably, writing and changing directories
# would not be allowed.
#
# also, make sure to create /mnt/shared by first
# doing : mkdir /mnt/shared
cap grant
path /mnt/shared
access rl
done

# Share the token
cap share 2

# Each capability can have an unlimited amount of tokens.
# It is possible to revoke either tokens or capabilities.
# Revoking capabilities will revoke all delegated capabilities.
# Revoking a token only revokes it directly, nothing else.
#
# You then read the newly minted token by doing :
cap list 2

# this is the result of the previous command :
2 /mnt/shared rl
    XXXXXXXXXXXXXXXXXXXX
# where `XXXXXXXXXXXXXXXXXXXX` is the token which can be shared
# and will be accepted in further sessions until it is revoked.

# Special one-shot short tokens can be created as well. These
# are made for convenience.
# like so:
cap share short 2

# At this point, it is possible to get a session in one of
# two ways, first way :
./telnetd.sh

# or

telnet localhost 9023

# it is possible to use 'netcat' as well as this is an extremely simple protocol.

# each method will ask for a token which must be copied and paste into it.

Token: XXXXXXXXXXXXXXXXXXXXXXXX
Token verified
/ $ 

Future Plans: Peer-to-Peer Mounting

The next major goal is implementing a mount command that allows mounting different filesystem types—including local directories, remote shares, and even HTTP endpoints. This will enable fully peer-to-peer operation where each device mounts and shares resources using its own capability tokens.

This project demonstrates that advanced operating system concepts can be prototyped in high-level languages like AWK. It also highlights the value of capability-based security models, even in constrained environments.

This project is being hosted in uTelnetd git repository

When a better name is found, it will also be mirrored on github for better convenience.

For comments: mastodon link