Skip to content

API.md

Latest commit

 

History

History
184 lines (129 loc) · 3.71 KB

API.md

File metadata and controls

184 lines (129 loc) · 3.71 KB

Deadend Lua API and Script Authoring Guide

This manual explains the script API how to write working service scripts.

If you wrote your own script, feel free to open PR in the repository to "examples" directory!

Sandbox

Scripts run in a restricted Lua environment.

Available standard libraries:

  • _G (base)
  • string
  • table
  • math
  • utf8

Unavailable by default:

  • io
  • os
  • package
  • debug

This is intentional to keep scripts isolated and predictable.

Deadend Namespace

Scripts interact with the client through the global table deadend.

deadend.send(data)

Signature:

  • deadend.send(string_data) -> boolean

Sends raw bytes to the connected client. Returns true on success, false if sending failed.

Example:

local ok = deadend.send("220 Service ready\r\n")
if not ok then
    return
end

deadend.recv(n)

Signature:

  • deadend.recv(integer_n) -> string | nil

Reads up to n bytes from the client. Returns nil when the peer disconnects or the read fails.

Constraints:

  • n must be in range 1..65535.

Example:

local req = deadend.recv(1024)
if not req then
    return
end

deadend.sleep(ms)

Signature:

  • deadend.sleep(integer_ms)

Pauses script execution for ms milliseconds.

Example:

deadend.sleep(500)

deadend.get_ip()

Signature:

  • deadend.get_ip() -> string

Returns the peer IP address.

Example:

local ip = deadend.get_ip()

deadend.log(message[, level])

Signature:

  • deadend.log(string_message, string_level?)

Writes a runtime log line to stdout from a Lua script. level is optional and defaults to "info".

Example:

deadend.log("smtp handshake started")
deadend.log("auth failure", "warn")

deadend.set_tarpit(base_ms[, jitter_ms])

Signature:

  • deadend.set_tarpit(integer_base_ms, integer_jitter_ms?)

Configures an automatic delay applied after each successful deadend.recv.

  • base_ms: fixed delay in milliseconds
  • jitter_ms: optional extra random delay in range 0..jitter_ms

Constraints:

  • each value must be in range 0..60000

Example:

deadend.set_tarpit(80, 40)

deadend.set_limits(recv_calls_limit[, recv_bytes_limit])

Signature:

  • deadend.set_limits(integer_recv_calls_limit, integer_recv_bytes_limit?)

Configures runtime receive limits for the current connection. When a limit is exceeded, deadend.recv returns nil and the socket is closed.

  • recv_calls_limit: max number of successful recv calls (0 disables this limit)
  • recv_bytes_limit: max cumulative bytes received (0 disables this limit)

Example:

deadend.set_limits(200, 262144)

deadend.close()

Signature:

  • deadend.close()

Closes the current client socket.

Example:

deadend.close()
return

Script Design Guidelines

  • Always handle nil from deadend.recv.
  • Keep state machines bounded (for example, max command loops).
  • Use deadend.set_tarpit and deadend.set_limits for connection throttling and abuse control.
  • Use explicit protocol states for better realism and maintainability.
  • Log important events (connect, auth, protocol errors, disconnect).
  • Close cleanly when done.

Naming and Port Mapping

A script file named <port>.lua serves that TCP port.

Examples:

  • 22.lua serves port 22
  • 80.lua serves port 80
  • 25.lua serves port 25
  • 5222.lua serves port 5222

Invalid names are ignored:

  • ssh.lua
  • 22.txt
  • 00000.lua
  • 70000.lua

Examples

See the examples directory for working scripts.

  • examples/25.lua: SMTP mock with command-state handling and script logging.
  • examples/5222.lua: XMPP client-stream mock with feature negotiation and script logging.

Compatibility

  • Lua 5.4 recommended.
  • API is intentionally small and stable.