OS Classification

This is a RedTeam Subnet OS Classification challenge repository.

Documentation page: https://docs.theredteam.io/latest/challenges

✨ Features

• RedTeam Subnet challenge
• Challenge module (Python package)
• Challenge controller and manager
• Challenge API (FastAPI)
• OS Classification submission flow:
  • miner_output.commit_files contains train.py and submissions.py
  • train.py receives a generated OS training CSV
  • submissions.py receives each generated OS test row plus the trained model

---

OS Classification Challenge Flow

Miners submit two Python files:

1. train.py
   • Called as python train.py <training_csv> <model_json>.
   • Receives a CSV split generated from the 350k OS source dataset.
   • Must write a valid JSON model file.
2. submissions.py
   • Exposes detect_os(features, model) -> str.
   • Runs inside the FlowPrint detector container.
   • Receives one row from the OS test CSV at a time and the JSON model produced by training.

The challenge API reads both files from miner_output.commit_files and mounts them with the generated OS training CSV into the isolated FlowPrint container. The container trains the model, keeps the model temporary for that scoring run, and serves inference while the challenge replays the generated OS test CSV.

Miners may not embed pretrained or externally generated model weights in either file. All learned weights must be produced by train.py from the generated OS training CSV during the current scoring run, and submissions.py may only consume them through its model argument.

The source dataset is:

volumes/storage/flowprint-challenge/data/flow_data_sampled_350k.csv

Despite the suffix, this file is Parquet. Convert it into real train/test CSV files before running the platform scorer. The label is device_os; every other column is an inference feature. The platform returns a macro F1 score based on per-class OS predictions.

{
  "miner_output": {
    "commit_files": [
      {"file_name": "train.py", "content": "..."},
      {"file_name": "submissions.py", "content": "..."}
    ]
  }
}

🐤 Getting Started

1. 🚧 Prerequisites

• Install docker and docker compose
  • Docker image: redteamsubnet61/flowprint-challenge

[OPTIONAL] For DEVELOPMENT environment:

• Install Python (>= v3.10) and pip (>= 23):
  • [RECOMMENDED] Miniconda (v3)
  • [arm64/aarch64] Miniforge (v3)
  • [Python virtual environment] venv
• Install git
• Install Git LFS if your dataset checkout uses LFS
• Setup an SSH key

2. 📥 Download or clone the repository

2.1. Prepare projects directory (if not exists):

# Create projects directory:
mkdir -pv ~/workspaces/projects

# Enter into projects directory:
cd ~/workspaces/projects

2.2. Follow one of the below options [A], [B] or [C]:

OPTION A. Clone the repository:

git clone https://github.com/RedTeamSubnet/flowprint_v1.git && \
    cd flowprint_v1 && \
    git lfs pull

OPTION B. Clone the repository (for DEVELOPMENT: git + ssh key):

git clone git@github.com:RedTeamSubnet/flowprint_v1.git && \
    cd flowprint_v1 && \
    git lfs pull

OPTION C. Download source code:

1. Download archived zip or tar.gz file from releases.
2. Extract it into the projects directory.
3. Enter into the project directory.

[OPTIONAL] Install dependencies (for DEVELOPMENT environment)

# For DEVELOPMENT environment, install dependencies with pip:
pip install -e .[dev]
# Install pre-commit hooks:
pre-commit install

3. 🌎 Configure environment variables

[NOTE] Please, check environment variables section for more details.

# Copy '.env.example' file to '.env' file:
cp -v ./.env.example ./.env
# Edit environment variables to fit in your environment:
nano ./.env

4. 🏁 Start the server

## OPTIONAL: Configure 'compose.override.yml' file.
# For DEVELOPMENT environment:
cp -v ./templates/compose/compose.override.dev.yml ./compose.override.yml
# Edit 'compose.override.yml' file to fit in your environment:
nano ./compose.override.yml

## 1. Check docker compose configuration is valid:
./compose.sh validate
# Or:
docker compose config

## 2. Start docker compose:
./compose.sh start -l
# Or:
docker compose up -d --remove-orphans --force-recreate && \
    docker compose logs -f -n 100

5. ✅ Check server is running

Check with CLI (curl):

# Send a ping request with 'curl' to REST API server and parse JSON response with 'jq':
curl -s http://localhost:10001/ping | jq

Check with web browser:

• Health check: http://localhost:10001/health
• Swagger: http://localhost:10001/docs
• Redoc: http://localhost:10001/redoc
• OpenAPI JSON: http://localhost:10001/openapi.json

6. 🛑 Stop the server

Docker runtime:

# Stop docker compose:
./compose.sh stop
# Or:
docker compose down --remove-orphans

👍

---

⚙️ Configuration

🌎 Environment Variables

.env.example:

## --- Environment variable --- ##
ENV=LOCAL
DEBUG=false
# TZ=UTC
# PYTHONDONTWRITEBYTECODE=1


## -- API configs -- ##
FLP_API_PORT=10001
# FLP_API_CONFIGS_DIR="/etc/flowprint-challenge"
# FLP_API_LOGS_DIR="/var/log/flowprint-challenge"
# FLP_API_DATA_DIR="/var/lib/flowprint-challenge"
# FLP_CHALLENGE_TRAIN_CSV_PATH="{data_dir}/os_train_data.csv"
# FLP_CHALLENGE_TEST_CSV_PATH="{data_dir}/os_test_data.csv"
# FLP_CHALLENGE_TRAINING_TIMEOUT_SECONDS=600
# FLP_API_TMP_DIR="/tmp/flowprint-challenge"
# FLP_API_VERSION="1"
# FLP_API_PREFIX=""
# FLP_API_DOCS_ENABLED=true
# FLP_API_DOCS_OPENAPI_URL="{api_prefix}/openapi.json"
# FLP_API_DOCS_DOCS_URL="{api_prefix}/docs"
# FLP_API_DOCS_REDOC_URL="{api_prefix}/redoc"

---

🏗️ Build Docker Image

Before building the docker image, make sure you have installed docker and docker compose.

To build the docker image, run the following command:

# Build docker image:
./scripts/build.sh
# Or:
docker compose build

📚 Documentation

• https://docs.theredteam.io/latest/challenges
• Docs index
• Testing manual
• Miner v2 submission guide

---

📑 References

• RedTeam Subnet: https://www.theredteam.io
• Bittensor: https://www.bittensor.com
• FastAPI - https://fastapi.tiangolo.com
• Docker - https://docs.docker.com
• Docker Compose - https://docs.docker.com/compose