backend package

Submodules

backend.config module

Module wrapping environment variables for configuration.

backend.container module

Contains class and methods used for handling docker containers

class backend.container.Containers

Bases: object

Class for handling docker containers, as well as format the parameters for them

HOME_VOLUME_SUFFIX = 'home'
ID_PREFIX = 'openssh-server'
LABEL_ROLE = 'botnet-honeypot.role'
NETLOG_CONTAINER_SUFFIX = '_netlog'
NETLOG_DIR = '/netlog'
NETLOG_FILE_PATH = '/netlog/log.pcap'
ROLE_TARGET_CONTAINER = 'target-container'
TCPDUMP_IMAGE = 'itsthenetwork/alpine-tcpdump'
create_container(config)
Creates a docker container with the specified container_id, exposes the specified SSH port,

and has SSH login credentials user/password

Parameters

config (dict) – Dictionary, preferrably formatted using format_config,

Return type

None

containing all environment variables and config needed for setting up a container.

destroy_container(container_id)

Destroy a specified container

Parameters

container_id (str) – ID (name) of container to be destroyed

Raises

ValueError – If container does not exist.

Return type

None

destroy_target_containers()

Clean up any remaining, previously started, containers.

static format_config(container_id, user, password, hostname='Dell-T140', user_id='1000', group_id='1000', timezone='Europe/London', sudo_access='true', image='target-container', port=None)

Formats the given parameters as a dictionary that fits docker-py. Creates the volumes for the config and home dirs of the container

Parameters

  • container_id (int) – Unique ID for container

  • user (str) – Username for container

  • password (str) – Password for container

  • volumes – Volumes on host to mount to the container.

  • hostname – Hostname for container, defaults to ‘Dell-T140’

  • user_id – UID for container user, defaults to ‘1000’

  • group_id – GID for container user, defaults to ‘1000’

  • timezone – Timezone for container, defaults to ‘Europe/London’

  • sudo_access – Sudo access for container, defaults to ‘true’

  • image – Image for container, defaults to ‘target-container’ which is based on ‘ghcr.io/linuxserver/openssh-server’

  • port – Exposed port for container, defaults to None

Returns

Dictionary that can be easily used for docker-py

Return type

dict

get_container_netlog(container_id)

Returns byte stream of pcap file for container with the given ID.

Parameters

container_id (str) – The target container to get the netlog file for.

Raises

ValueError – If container is not stopped or does not exist.

Returns

Byte stream of pcap file

Return type

IO[bytes]

get_container_port(container_id)

Returns the port bound to a container. Undefined if multiple ports are used.

Parameters

container_id (str) – The container id

Returns

The port bound to container container_id

Return type

int

get_volume(volume_id)

Returns the specified volume in form <Volume: short_id>, where short_id is the volume id truncated to 10 characters

Parameters

volume_id (str) – The name of the volume

Return type

docker.models.volumes.Volume

prune_volumes()

Removes storage volumes for all inactive (destroyed) containers.

remove_container_volumes(container_id)

Removes all volumes associated with a specific target container.

Parameters

container_id (str) – The ID of the container whose

volumes should be removed.

status_container(container_id)

Return the status of a specific container with the container_id argument

Parameters

container_id (str) – ID (name) of container

Returns

Returns an enum describing the status of a container

Return type

backend.container.Status

stop_container(container_id)

Stop a specified container

Parameters

container_id (str) – ID (name) of container to be stopped

Return type

None

class backend.container.Status(value)

Bases: enum.Enum

Enum for the status of a container

EXITED = 'exited'
NOTFOUND = 'not found'
PAUSED = 'paused'
RESTARTING = 'restarting'
RUNNING = 'running'
UNDEFINED = 'undefined'

backend.http_server module

Module implementing a gRPC HTTP API.

Currently handles requests to acquire and yield target systems.

backend.http_server.start_http_server(container_handler, keep_volumes, target_system_address, bind_address='localhost:80')

Starts a gRPC HTTP server with pre-configured services.

Parameters

  • container_handler (backend.container.Containers) – Container handler to use for managing containers in response to service requests.

  • port – The TCP port to run the server on, defaults to 80.

  • keep_volumes (bool) –

  • target_system_address (str) –

  • bind_address (str) –

Returns

The gRPC server that was started.

Return type

grpc.Server

backend.io module

Module for IO-related utilties

backend.io.byte_stream_from_iterable(iterable, buffer_size=8192)

Source: https://gist.github.com/mechanical-snail/7688353

Lets you use an iterable (e.g. a generator) that yields bytestrings as a read-only input stream.

The stream implements Python 3’s newer I/O API (available in Python 2’s io module). For efficiency, the stream is buffered.

Parameters

iterable (Iterable[bytes]) –

Return type

IO[bytes]