cybersecnatlab/socaz repository overview

⁠SoCaz - alternative to socat with special features for CTFs

Example: ./socaz --bind 1337 --cmd "python3 ./test.py" or ./socaz --bind 1337 -- python3 ./test.py

Usage: socaz [OPTIONS] --bind <BIND> [CMD]...

Arguments:
  [CMD]...  Command to execute [e.g. "run.sh", "python ./script.py", ...]

Options:
  -b, --bind <BIND>
          Bind address [e.g. 0.0.0.0:8000 or 8000], if host is omitted, it will be bound to all interfaces
  -c, --cmd <CMD>
          Command to execute [e.g. "run.sh", "python ./script.py", ...]
  -e, --stderr
          Redirect stderr to TCP connection
  -d, --debug
          Redirect stderr to socaz stderr
  -t, --timeout <TIMEOUT>
          Timeout in seconds (0 = unlimited) [default: 0]
      --max-connections <MAX_CONNECTIONS>
          Maximum number of connections
      --max-connections-ip <MAX_IP_CONNECTIONS>
          Maximum number of connections by ip (requires --drop-connections)
      --drop-connections
          Drop connections after MAX_CONNECTIONS is reached (default: wait for previous connections to finish)
  -u, --uid <UID>
          Drop privileges to UID (unix only)
  -g, --gid <GID>
          Drop privileges to GID (unix only)
  -v, --verbose
          Verbose output
  -F, --flag <FLAG>
          Flag to pass as env, use the flag format described in the documentation (e.g. "flag{TEST_[random 8]}")
      --flag-from-env <ENV_VAR>
          Environment variable containing the flag to pass as env, use the flag format described in the documentation (e.g. "flag{TEST_[random 8]}")
      --clear-env
          Clear environment variables before executing the command
      --keep-env <ENV_VARS>
          Keep only the specified environment variables (comma separated) [e.g. "PATH,USER"]
  -P, --pow [<BITS>]
          Proof of work bits [default: 20]
      --cleanup-cmd <CMD>
          Command to execute after the execution of the main command, even on timeout or connection closed [e.g. "cleanup.sh", "python ./cleanup.py", ...]. It inherits the environment variables from Socaz and it will not be killed by Socaz!
  -h, --help
          Print help
  -V, --version
          Print version

⁠Flag format

A flag is a string that can contain instructions. Instructions are composed of a command and 0 or many filters. Instructions are enclosed in square brackets ([]). Filters are separated by a pipe (|). Filters can be chained.

Commands:

• random N: Generate a random string of N [0-9a-f] characters
• ip: Get the IP address of the client

Filters:

• hash: Hash the string with sha256 returning an hex string
• base64: Encode the string in base64
• cut N: Cut the string at the Nth character (keep the first N characters)
• encrypt KEY [NONCE_LENGTH]: Encrypt using ChaCha20 with KEY and a random NONCE_LENGTH (default: 4) nonce (see "Encryption and signature" section)
• sign KEY [SIGNATURE_LENGTH]: Sign using HMAC-SHA256 with KEY producing a signature with length SIGNATURE_LENGTH (default: 4) (see "Encryption and signature" section)

Example: flag{something_[random 16|hash|cut 8]_something_else_[ip|base64]_something_else}
Example output: flag{something_9598f995_something_else_MTI3LjAuMC4x_something_else}

⁠Encryption and signature

⁠Encryption

The encryption is done using ChaCha20. The nonce is generated randomly and is prepended to the encrypted data. The nonce length is specified in bytes in the filter (default: 4).

Steps:

1. Generate a random nonce (called "small nonce", to be prepended to the output) of length NONCE_LENGTH
2. Derive the "real key" from the "small key" (provided by the user) using SHA256 (length: 32 bytes)
3. Derive the "real nonce" from the "small nonce" using SHA256 (length: 12 bytes)
4. Encrypt the data using ChaCha20 with the "real nonce" and the "real key"
5. Output "small nonce" + cyphertext

⁠Signature

The signature is done using HMAC-SHA256. The signature length is specified in bytes in the filter (default: 4).

Steps:

1. Generate a signature using HMAC-SHA256 with the key and the data
2. Output "signature" (signature is cut to SIGNATURE_LENGTH bytes)

⁠Other features

⁠Proof of Work (PoW) (optional)

Proof of Work is implemented to prevent DoS attacks.
The PoW (-P/--pow) is done using Hashcash (https://en.wikipedia.org/wiki/Hashcash⁠) with N bits (specified by the argument, default 20) and a random case-sensitive resource generated each connection by Socaz.

Example of PoW prompt

Do Hashcash for 20 bits with resource "WXm98Mz89uQb"
https://pow.cybersecnatlab.it/?data=WXm98Mz89uQb&bits=20
or
hashcash -mCb20 "WXm98Mz89uQb"
Result: