flagonfly 0.0.1__tar.gz

flagonfly-0.0.1/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.3
+Name: flagonfly
+Version: 0.0.1
+Summary: Add your description here
+Author: aidnem
+Author-email: aidnem <aidnem@noreply.codeberg.org>
+Requires-Dist: bitstring>=4.4.0
+Requires-Dist: click>=8.4.1
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# flagonfly
+
+The ultimate CTF tool. Designed to combat the staggering lack of cross-platform CTF tools. Named after the ultimate hunter, the dragonfly. 
+
+## Installation
+
+For now, flagonfly is not published to any package repositories. To install it, use `pip` or `uv`:
+
+1. First, clone the repository somewhere convenient. Change directory into the project:
+
+```sh
+git clone https://codeberg.org/aidnem/flagonfly.git
+cd flagonfly
+```
+
+2. Install the package using your package manager of choice.
+
+It's preferable to use a package manager that will install the project in its own isolated environment, such as `uv tool install` or `pipx install`.
+
+Install the project in editable mode (use the `-e` flag) so that it can be updated by running `git pull` at a later time:
+
+```sh
+uv tool install -e .
+```
+
+Alternatively, use pipx:
+
+```sh
+pipx install -e .
+```
+
+Finally, if you prefer pip, you can use that instead. Keep in mind that this will install the dependencies to your global pip environment:
+
+```sh
+pip install -e .
+```
+
+Installing using any of these 3 methods will add 3 executables to your python script path:
+
+- `flagonfly` - The flagonfly CLI. This is how all CLI tools can be used.
+- `flf` - A convenient alias for `flagonfly`. Because the command is intended to be deeply composed (e.g. `cat data | flf encode binary | rev | flf decode binary`), a shorter alias is useful in saving time composing commands.
+- `flagonfly-gui` - Launches the flagonfly GUI, a tkinter app that is intended to provide some of the functionality of the flagonfly library in a graphical form.
+
+## Core Library
+
+The flagonfly project is separated into core, UI, and CLI projects so that the central functionality of the can be used from other projects. Please note that, during early development, doc comments will likely be sparse. To use the functionality of flagonfly in other projects, look into importing necessary functions and packages from `flagonfly.core`.
+
+## CLI: Subcommands
+
+### Help
+
+Flagonfly contains detailed help messages for commands and their parameters wherever possible. Use the `--help` flag on any command to see detailed descriptions of the arguments.
+
+This is important because this README will likely be updated less often and less thoroughly than the help messages themselves.
+
+### Encode/decode
+
+Use `flagonfly encode` or `flagonfly decode` followed by a format to convert data to different formats.
+
+For example, `echo "Hello, world!" | flagonfly encode binary` will encode the ASCII text into binary and output it as a string of "1"s and "0"s. The `decode` command does the reverse.
+
+If an encoding isn't specified when decoding, flagonfly will attempt to guess at what encoding was used. It does this by attempting to decode using various encodings in order until one succeeds. This is not foolproof; if you data was encoded in a larger format but using only certain digits (e.g. data encoded as hex that only uses 1s and 0s), it will decode incorrectly. However, it's good enough as a first try for decoding data quickly.
+
+#### Words and separators
+
+By default, the output of `encode` is divided into words, separated by a separator string. There are sensible defaults for all data types, and the separator/word length parameters are ignored when encoding to base64/32/16.
+
+To change the separator, pass a string to the `-s`/`--separator` option. To remove the separator, pass an empty string: `flagonfly encode -s "" ...`.
+
+To change the word size, use the `-w` or `--word-length` option.
+
+#### Prefixes
+The `-p`/`--prefix` option can be used to append a prefix (e.g. `0b` for binary data). When using no separator, this prefix is appended to the beginning of the output. When using a separator between words, it will be appended to the beginning of each word.
+
+There is no prefix for base64/32/16 data.
+
+## CI Usage
+
+The flagonfly project will hopefully leverage Codeberg's hosted woodpecker instance for continuous integration. Its needs are fairly bare-bones: running unit tests on all PRs to main, and running an automatic publish workflow to publish the project to PyPI automatically whenever a new release is tagged. The processing, memory, and storage requirements of these workflows should be minimal, as the project will hopefully remain quite small.

flagonfly-0.0.1/README.md

@@ -0,0 +1,79 @@
+# flagonfly
+
+The ultimate CTF tool. Designed to combat the staggering lack of cross-platform CTF tools. Named after the ultimate hunter, the dragonfly. 
+
+## Installation
+
+For now, flagonfly is not published to any package repositories. To install it, use `pip` or `uv`:
+
+1. First, clone the repository somewhere convenient. Change directory into the project:
+
+```sh
+git clone https://codeberg.org/aidnem/flagonfly.git
+cd flagonfly
+```
+
+2. Install the package using your package manager of choice.
+
+It's preferable to use a package manager that will install the project in its own isolated environment, such as `uv tool install` or `pipx install`.
+
+Install the project in editable mode (use the `-e` flag) so that it can be updated by running `git pull` at a later time:
+
+```sh
+uv tool install -e .
+```
+
+Alternatively, use pipx:
+
+```sh
+pipx install -e .
+```
+
+Finally, if you prefer pip, you can use that instead. Keep in mind that this will install the dependencies to your global pip environment:
+
+```sh
+pip install -e .
+```
+
+Installing using any of these 3 methods will add 3 executables to your python script path:
+
+- `flagonfly` - The flagonfly CLI. This is how all CLI tools can be used.
+- `flf` - A convenient alias for `flagonfly`. Because the command is intended to be deeply composed (e.g. `cat data | flf encode binary | rev | flf decode binary`), a shorter alias is useful in saving time composing commands.
+- `flagonfly-gui` - Launches the flagonfly GUI, a tkinter app that is intended to provide some of the functionality of the flagonfly library in a graphical form.
+
+## Core Library
+
+The flagonfly project is separated into core, UI, and CLI projects so that the central functionality of the can be used from other projects. Please note that, during early development, doc comments will likely be sparse. To use the functionality of flagonfly in other projects, look into importing necessary functions and packages from `flagonfly.core`.
+
+## CLI: Subcommands
+
+### Help
+
+Flagonfly contains detailed help messages for commands and their parameters wherever possible. Use the `--help` flag on any command to see detailed descriptions of the arguments.
+
+This is important because this README will likely be updated less often and less thoroughly than the help messages themselves.
+
+### Encode/decode
+
+Use `flagonfly encode` or `flagonfly decode` followed by a format to convert data to different formats.
+
+For example, `echo "Hello, world!" | flagonfly encode binary` will encode the ASCII text into binary and output it as a string of "1"s and "0"s. The `decode` command does the reverse.
+
+If an encoding isn't specified when decoding, flagonfly will attempt to guess at what encoding was used. It does this by attempting to decode using various encodings in order until one succeeds. This is not foolproof; if you data was encoded in a larger format but using only certain digits (e.g. data encoded as hex that only uses 1s and 0s), it will decode incorrectly. However, it's good enough as a first try for decoding data quickly.
+
+#### Words and separators
+
+By default, the output of `encode` is divided into words, separated by a separator string. There are sensible defaults for all data types, and the separator/word length parameters are ignored when encoding to base64/32/16.
+
+To change the separator, pass a string to the `-s`/`--separator` option. To remove the separator, pass an empty string: `flagonfly encode -s "" ...`.
+
+To change the word size, use the `-w` or `--word-length` option.
+
+#### Prefixes
+The `-p`/`--prefix` option can be used to append a prefix (e.g. `0b` for binary data). When using no separator, this prefix is appended to the beginning of the output. When using a separator between words, it will be appended to the beginning of each word.
+
+There is no prefix for base64/32/16 data.
+
+## CI Usage
+
+The flagonfly project will hopefully leverage Codeberg's hosted woodpecker instance for continuous integration. Its needs are fairly bare-bones: running unit tests on all PRs to main, and running an automatic publish workflow to publish the project to PyPI automatically whenever a new release is tagged. The processing, memory, and storage requirements of these workflows should be minimal, as the project will hopefully remain quite small.

flagonfly-0.0.1/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "flagonfly"
+version = "0.0.1"
+description = "Add your description here"
+readme = "README.md"
+authors = [{ name = "aidnem", email = "aidnem@noreply.codeberg.org" }]
+requires-python = ">=3.13"
+dependencies = ["bitstring>=4.4.0", "click>=8.4.1"]
+
+[project.scripts]
+flagonfly = "flagonfly.cli:main"
+flf = "flagonfly.cli:main"
+
+[project.gui-scripts]
+flagonfly-gui = "flagonfly.gui:main"
+
+[build-system]
+requires = ["uv_build>=0.11.21,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "mypy>=2.1.0",
+    "pytest>=9.1.1",
+]
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true

flagonfly-0.0.1/src/flagonfly/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

flagonfly-0.0.1/src/flagonfly/__main__.py

@@ -0,0 +1,4 @@
+from flagonfly.cli import main
+
+if __name__ == "__main__":
+    main()

flagonfly-0.0.1/src/flagonfly/cli.py

@@ -0,0 +1,11 @@
+import click
+from flagonfly.commands.codec_commands import encode, decode
+
+
+@click.group()
+def main():
+    """flagonfly CLI toolkit"""
+
+
+main.add_command(encode)
+main.add_command(decode)

flagonfly-0.0.1/src/flagonfly/cli_complete.py

@@ -0,0 +1,54 @@
+"""flagonfly CLI completion utility, for automatically picking an option based on a partial string"""
+
+from typing import Iterable
+
+import click
+import sys
+
+
+def complete_one_strict(inp: str, options: Iterable[str]) -> str:
+    """
+    Exactly like complete_one, but exits instead of returning None if a match isn't found.
+    """
+
+    result = complete_one(inp, options)
+
+    if result is None:
+        click.echo(
+            f"[ERROR] Input '{inp}' did not match any of {options}.",
+            file=sys.stderr,
+        )
+
+        sys.exit(1)
+
+    return result
+
+
+def complete_one(inp: str, options: Iterable[str]) -> str | None:
+    """
+    Given an input string and an Iterable of options, pick the first option that starts with the input string.
+
+    If the input is an exact match, returns that immediately.
+
+    Prints a warning if multiple options are available.
+
+    If no matches are found, returns None.
+    """
+
+    if inp in options:
+        return inp
+
+    filtered_options = list(filter(lambda option: option.startswith(inp), options))
+
+    if len(filtered_options) == 0:
+        return None
+
+    selected_option = filtered_options[0]
+
+    if len(filtered_options) != 1:
+        click.echo(
+            f"[WARNING] Ambigious input '{inp}' matches multiple options ({filtered_options}), so first option was selected: '{selected_option}'.",
+            file=sys.stderr,
+        )
+
+    return selected_option

flagonfly-0.0.1/src/flagonfly/cli_message_constants.py

@@ -0,0 +1,4 @@
+"""flagonfly's reusable help messages for common parameters that will be used between multiple subcommands"""
+
+INPUT_FILE_HELP = "File to read for input. Defaults to `-`, meaning stdin."
+OUTPUT_FILE_HELP = "File where output will be written. Defaults to `-`, meaning stdout."

flagonfly-0.0.1/src/flagonfly/commands/codec_commands.py

@@ -0,0 +1,233 @@
+"""
+flagonfly codex tools CLI bindings
+"""
+
+import base64
+import sys
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import IO, Callable
+
+import click
+
+from flagonfly.cli_message_constants import INPUT_FILE_HELP, OUTPUT_FILE_HELP
+from flagonfly.core import codec
+
+
+@dataclass(frozen=True)
+class Codec:
+    encode_func: Callable[[bytes, bool, str, int], str]
+    decode_func: Callable[[str, str], bytes | None]
+    default_word_length: int
+
+
+class Encoding(StrEnum):
+    BINARY = "binary"
+    HEX = "hex"
+    BASE64 = "b64"
+    URLSAFE_BASE64 = "b64url"
+    BASE32 = "b32"
+    BASE16 = "b16"
+    GUESS = "guess"
+
+
+def guess_encode_wrapper(
+    data: bytes, prefix: bool, separator: str, word_length: int
+) -> str:
+    click.echo(
+        "[WARN] Best-guess is not supported while encoding; using binary instead",
+        file=sys.stderr,
+    )
+
+    return codec.binary_encode(data, prefix, separator, word_length)
+
+
+def wrap_encode_func_ignoring_separator(
+    encode_func: Callable[[bytes], str],
+) -> Callable[[bytes, bool, str, int], str]:
+    """
+    Given an encoding function that takes bytes and returns a string, wrap it in a function that accepts but ignores all other encoding arguments.
+
+    This function exists to provide an easy way to make base64 functions fit the interface required for CLI commands.
+    """
+    return lambda data, _prefix, _separator, _word_length: encode_func(data)
+
+
+def wrap_b64encode(
+    encode_func: Callable[[bytes], bytes],
+) -> Callable[[bytes, bool, str, int], str]:
+    return wrap_encode_func_ignoring_separator(lambda data: encode_func(data).decode())
+
+
+def wrap_b64decode(
+    decode_func: Callable[[str], bytes],
+) -> Callable[[str, str], bytes]:
+    """
+    Given a ecoding function that takes a string and returns bytes, wrap it in a function that accepts but ignores all other decoding arguments.
+
+    This function exists to provide an easy way to make base64 functions fit the interface required for CLI commands.
+    """
+    return lambda data, _: decode_func(data)
+
+
+ENCODINGS: dict[Encoding, Codec] = {
+    Encoding.BINARY: Codec(codec.binary_encode, codec.binary_decode, 8),
+    Encoding.HEX: Codec(codec.hex_encode, codec.hex_decode, 2),
+    Encoding.BASE64: Codec(
+        wrap_b64encode(base64.b64encode),
+        wrap_b64decode(lambda data: base64.b64decode(data)),
+        1,
+    ),
+    Encoding.URLSAFE_BASE64: Codec(
+        wrap_b64encode(base64.urlsafe_b64encode),
+        wrap_b64decode(lambda data: base64.urlsafe_b64decode(data)),
+        1,
+    ),
+    Encoding.BASE32: Codec(
+        wrap_b64encode(base64.b32encode),
+        wrap_b64decode(lambda data: base64.b32decode(data)),
+        1,
+    ),
+    Encoding.BASE16: Codec(
+        wrap_b64encode(base64.b16encode),
+        wrap_b64decode(lambda data: base64.b16decode(data)),
+        1,
+    ),
+    Encoding.GUESS: Codec(guess_encode_wrapper, codec.guess_decode, 8),
+}
+
+SEPARATOR_HELP = "Separator placed between words (ignored in base64/32/16). Defaults to a single space."
+INVALID_ENCODING_MSG = f"[ERROR] Invalid encoding chosen. Please choose one of {[e.value for e in Encoding]}."
+
+
+@click.command()
+@click.argument(
+    "encoding",
+    type=click.Choice(
+        [e.value for e in Encoding],
+        case_sensitive=False,
+    ),
+    default=Encoding.BINARY,
+)
+@click.option(
+    "-i",
+    "--input",
+    type=click.File("rb"),
+    default="-",
+    help=INPUT_FILE_HELP,
+)
+@click.option(
+    "-t",
+    "--trim",
+    is_flag=True,
+    help="Trim trailing newlines from input (helpful on Windows where `\\r\\n` is appended to echoed text)",
+)
+@click.option(
+    "-p",
+    "--prefix",
+    is_flag=True,
+    help="Include an integer literal prefix on the output (e.g. 0b for binary)",
+)
+@click.option(
+    "-s",
+    "--separator",
+    type=click.STRING,
+    default=" ",
+    help=SEPARATOR_HELP,
+)
+@click.option(
+    "-w",
+    "--word-length",
+    "word_length",
+    type=click.INT,
+    help="Defaults: 8 for binary, 2 for hex, 3 for octal",
+)
+@click.option(
+    "-o",
+    "--output",
+    type=click.File("wb"),
+    default="-",
+    help=OUTPUT_FILE_HELP,
+)
+def encode(
+    encoding: Encoding,
+    input: IO[bytes],
+    trim: bool,
+    prefix: bool,
+    separator: str,
+    word_length: int | None,
+    output: IO[bytes],
+) -> None:
+    """
+    Encode binary input as a string
+
+    \b
+    Notes:
+        -w/--word-length splits output into N-digit words (default 8 for binary, 2 for hex, 3 for octal)
+        If -s/--separator is empty, words are concatenated with no delimiter
+        -p/--prefix prepends the prefix to each word individually, unless an empty string is passed as the separator, in which case the entire output is treated as one word and the prefix is prepended once at the beginning.
+        Last word may be shorter than word-length if data isn't a round multiple.
+        Separator and word length are ignored for base64, as base64 is generated as one continuous string.
+        Octal data is padded to [word-length]-digit words unless -s/--separator is empty.
+    """
+    # TODO: Figure out how to use complete_one here...
+
+    try:
+        c = ENCODINGS[encoding]
+    except KeyError:
+        click.echo(INVALID_ENCODING_MSG, file=sys.stderr)
+        sys.exit(1)
+    word_length = word_length if word_length is not None else c.default_word_length
+    encode_func = c.encode_func
+
+    output.write(
+        encode_func(
+            input.read().rstrip(b"\r\n"), prefix, separator, word_length
+        ).encode()
+    )
+
+
+@click.command()
+@click.argument(
+    "encoding",
+    type=click.Choice(
+        [e.value for e in Encoding],
+        case_sensitive=False,
+    ),
+    default=Encoding.GUESS,
+)
+@click.option("-i", "--input", type=click.File("rb"), default="-", help=INPUT_FILE_HELP)
+@click.option("-s", "--separator", type=click.STRING, default=" ", help=SEPARATOR_HELP)
+@click.option(
+    "-o", "--output", type=click.File("wb"), default="-", help=OUTPUT_FILE_HELP
+)
+def decode(
+    encoding: Encoding, input: IO[bytes], separator: str, output: IO[bytes]
+) -> None:
+    """
+    Given an encoded string as input, convert to binary data
+
+    \b
+    Notes:
+        If input data type is unknown, don't specify an encoding (or use `guess`, the default) to automatically determine what encoding was used.
+        Because binary, hex, and base64/32/16 share characters, `guess` will misidentify ambiguous input (e.g. hex containing only 1s and 0s). Always prefer explicitly stating an encoding when possible, especially if the results from `guess` don't make sense.
+        If data can't be decoded, the original input will be output instead.
+        The separator is automatically removed from the input data, but if it is not found it serves as a noop. However, if words are individually prefixed, the
+        separator must be specified in order to detect and remove word prefixes.
+    """
+    try:
+        decode_func = ENCODINGS[encoding].decode_func
+    except KeyError:
+        click.echo(INVALID_ENCODING_MSG, file=sys.stdout)
+        sys.exit(1)
+
+    input_data = input.read()
+    result = decode_func(input_data.decode().strip(), separator)
+
+    if result is not None:
+        output.write(result)
+    else:
+        click.echo(
+            "[ERROR] Failed to decode text. Mirroring input instead.", file=sys.stderr
+        )
+        output.write(input_data)

flagonfly-0.0.1/src/flagonfly/core/codec.py

@@ -0,0 +1,119 @@
+"""
+flagonfly tools for changing data codec.
+
+Supports encoding and decoding of:
+    - binary
+    - hex
+    - base64/32/16 (in `guess` decoding only)
+"""
+
+import base64
+import binascii
+from typing import Callable, TypeAlias
+
+
+def binary_encode(
+    data: bytes, prefix: bool = False, separator: str = " ", word_length: int = 8
+) -> str:
+    # Get all bits as a string of 1s and 0s
+    bits: str = "".join(f"{byte:08b}" for byte in data)
+    # Chunk into words and separate by separator
+    # Only prefix every word if prefixing is enabled and there is a separator
+    word_prefix = "0b" if prefix and separator != "" else ""
+    words = [
+        word_prefix + bits[i : i + word_length]
+        for i in range(0, len(bits), word_length)
+    ]
+
+    # Only prefix entire string if prefixing is enabled and there is no separator
+    prefix_str = "0b" if prefix and separator == "" else ""
+    return prefix_str + separator.join(words)
+
+
+def binary_decode(data: str, separator: str = " ") -> bytes | None:
+    """Decode a string of 1s and 0s, optionally prefixed with 0b, optionally separated by `separator`. If the string doesn't
+    contain `separator`, it will be ignored."""
+    if separator:
+        words = [w.removeprefix("0b") for w in data.split(separator)]
+        data = "".join(words)
+    else:
+        data = data.removeprefix("0b")
+    # Convert each byte to an int
+    try:
+        byte_list = [int(data[i : i + 8], 2) for i in range(0, len(data), 8)]
+    except ValueError:
+        return None
+
+    # Convert list of ints to a bytes object
+    return bytes(byte_list)
+
+
+def hex_encode(
+    data: bytes, prefix: bool = False, separator: str = " ", word_length: int = 2
+) -> str:
+    hex_str = data.hex()
+    word_prefix = "0x" if prefix and separator != "" else ""
+
+    words = [
+        word_prefix + hex_str[i : i + word_length]
+        for i in range(0, len(hex_str), word_length)
+    ]
+
+    # Only prefix entire string if prefixing is enabled and there is no separator
+    prefix_str = "0x" if prefix and separator == "" else ""
+    return prefix_str + separator.join(words)
+
+
+def hex_decode(data: str, separator: str = " ") -> bytes | None:
+    """Decode a string of hexadecimal data, optionally prefixed with 0x, optionally separated by `separator`. If the string doesn't
+    contain `separator`, it will be ignored."""
+    if separator:
+        words = [w.removeprefix("0x") for w in data.split(separator)]
+        data = "".join(words)
+    else:
+        data = data.removeprefix("0x")
+    # Remove separator
+    data = data.replace(separator, "")
+    # Convert each byte to an int
+    # Convert list of ints to a bytes object
+    try:
+        return bytes.fromhex(data)
+    except ValueError:
+        return None
+
+
+DecodeFunc: TypeAlias = Callable[[str, str], bytes | None]
+
+
+_B64_DECODE_FUNCS = (
+    base64.b16decode,
+    base64.b32decode,
+    base64.b64decode,
+    base64.urlsafe_b64decode,
+)
+
+
+def get_guess_b64_decoded_data(data_with_separator_removed: str) -> bytes | None:
+    for f in _B64_DECODE_FUNCS:
+        try:
+            data = f(data_with_separator_removed)
+            return data
+        except binascii.Error:
+            pass
+
+    return None
+
+
+_GUESS_DECODE_FUNCS = (
+    binary_decode,
+    hex_decode,
+    lambda data, _sep: get_guess_b64_decoded_data(data),
+)
+
+
+def guess_decode(data: str, separator: str = " ") -> bytes | None:
+    for func in _GUESS_DECODE_FUNCS:
+        if (d := func(data, separator)) is not None:
+            return d
+
+    return None

flagonfly-0.0.1/src/flagonfly/gui.py

@@ -0,0 +1,11 @@
+import tkinter as tk
+
+
+def main():
+    root = tk.Tk()
+    root.title("flagonfly")
+
+    tk.Label(root, text="flagonfly").pack()
+    tk.Label(root, text="Functionality coming soon...").pack()
+
+    root.mainloop()