{"id":23114362,"url":"https://github.com/thealpha16/isolet","last_synced_at":"2025-08-16T20:32:01.150Z","repository":{"id":215570241,"uuid":"739246004","full_name":"TheAlpha16/isolet","owner":"TheAlpha16","description":"Isolet is a framework to deploy linux wargames like Bandit. It uses pre-configured templates to provide isolated instance using kubernetes pods for each user.","archived":false,"fork":false,"pushed_at":"2024-12-13T03:45:21.000Z","size":1719,"stargazers_count":0,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2024-12-13T04:25:42.417Z","etag":null,"topics":["ctf-framework","ctf-platform","helm-charts","kubernetes","wargame-platform"],"latest_commit_sha":null,"homepage":"https://unixit.infosec.org.in","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TheAlpha16.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-01-05T05:30:48.000Z","updated_at":"2024-12-13T03:45:26.000Z","dependencies_parsed_at":"2024-11-01T15:24:22.635Z","dependency_job_id":"5726159b-b003-48a3-a0f2-05d982040e2d","html_url":"https://github.com/TheAlpha16/isolet","commit_stats":null,"previous_names":["cyberlabs-infosec/isolet"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheAlpha16%2Fisolet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheAlpha16%2Fisolet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheAlpha16%2Fisolet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheAlpha16%2Fisolet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TheAlpha16","download_url":"https://codeload.github.com/TheAlpha16/isolet/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230057987,"owners_count":18166178,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ctf-framework","ctf-platform","helm-charts","kubernetes","wargame-platform"],"created_at":"2024-12-17T03:29:45.416Z","updated_at":"2025-08-16T20:32:01.138Z","avatar_url":"https://github.com/TheAlpha16.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# isolet\n\nIsolet is a framework to deploy linux wargames like [Bandit](https://overthewire.org/wargames/bandit/). It uses pre-configured templates to provide isolated instance using kubernetes pods for each user.\n\n\u003e [!note]\n\u003e README is outdated :)\n\u003e will update it soon\n\n## Contents\n\n- [Features](#features)\n- [Tech Stack](#tech-stack)\n- [Setup](#setup)\n- [Installation](#installation)\n- [Configuration](#configuration)\n  - [General](#general)\n  - [Instance](#instance)\n  - [Secrets](#secrets)\n\n## Features\n\n- Isolated access to each pod\n- Kubernetes manages the pods and scaling\n- Limited time for each instance\n- Instances can be extended\n- Run time variables to avoid rebuilding images\n- Email verification for registration\n\n## Tech Stack\n\n- Go\n- TypeScript\n- ReactJS\n- TailwindCSS\n- Kubernetes\n\n## Setup\n\nClone the repository\n\n```sh\ngit clone https://github.com/TheAlpha16/isolet.git\n```\n\nThis setup is specific for Standard [GKE](https://cloud.google.com/kubernetes-engine/) cluster. Check out the documentation of your service provider for specifics.\n\n- `StorageClass`\n  Isolet by default uses `standard-rwo` which supports only `ReadWriteOnce` the volume can be mounted as read-write by a single node. To change the `StorageClass` check the options available in your cluster\n\n```sh\nkubectl get sc\n```\n\nChoose an appropriate one and replace `standard-rwo` it in the [db-volume.yml](./kubernetes/init/db-volume.yml) file.\n\n```yml\nmetadata:\n  name: db-pv-claim\nspec:\n  storageClassName: standard-rwo\n  accessModes:\n    - ReadWriteOnce\n```\n\n- `NodePort`\n  Isolet uses service of type `NodePort` to expose pods for the user. You might need to configure your cloud services to allow traffic into the instances.\n\nWhile creating node you need to add network tag to the node. Like in the sample above nodes are being added `isolet-node`.\n\n```sh\ngcloud compute firewall-rules create kube-node-port-fw-rule \\\n    --action allow \\\n    --target-tags isolet-node \\\n    --source-ranges 0.0.0.0/0 \\\n    --rules tcp:30000-32767 \\\n    --no-enable-logging\n```\n\n- `ExternalIP`\n  If you have a static IP address to use, especially useful in case you want to setup domain name for your deployment, replace the IP address in the `loadBalancerIP` field of proxy-service in [proxy-main.yml](./kubernetes/definition/proxy-main.yml)\n\n```yml\napiVersion: v1\nkind: Service\nmetadata:\n  name: proxy-svc\n  labels:\n    app: proxy-svc\nspec:\n  ports:\n    - port: 80\n  selector:\n    app: proxy\n  type: LoadBalancer\n  loadBalancerIP: 35.23.13.211\n```\n\nTo reserve a static external IP address in GCP\n\n```sh\ngcloud compute addresses create \u003cNAME_OF_THE_IP\u003e --project=\u003cPROJECT_ID\u003e --region=us-central1\n```\n\n## Installation\n\n1. Install [kubectl](https://kubernetes.io/docs/tasks/tools/) on your machine\n2. Spin up a cluster on your favourite cloud provider or if you wish to test locally, install [minikube](https://minikube.sigs.k8s.io/docs/start/)\n\nHere is a sample gcloud command line for the cluster\n\n```sh\ngcloud beta container --project \u003cPROJECT_ID\u003e clusters create \u003cCLUSTER_NAME\u003e --no-enable-basic-auth --cluster-version \"1.27.7-gke.1121000\" --release-channel \"regular\" --machine-type \"e2-medium\" --image-type \"COS_CONTAINERD\" --disk-type \"pd-balanced\" --disk-size \"30\" --node-labels app=node --metadata disable-legacy-endpoints=true --scopes \"https://www.googleapis.com/auth/devstorage.read_only\",\"https://www.googleapis.com/auth/logging.write\",\"https://www.googleapis.com/auth/monitoring\",\"https://www.googleapis.com/auth/servicecontrol\",\"https://www.googleapis.com/auth/service.management.readonly\",\"https://www.googleapis.com/auth/trace.append\" --num-nodes \"1\" --logging=SYSTEM,WORKLOAD --monitoring=SYSTEM --enable-ip-alias --network \"projects/\u003cPROJECT_NAME\u003e/global/networks/default\" --subnetwork \"projects/\u003cPROJECT_NAME\u003e/regions/\u003cPROJECT_REGION\u003e/subnetworks/default\" --no-enable-intra-node-visibility --default-max-pods-per-node \"110\" --security-posture=standard --workload-vulnerability-scanning=disabled --enable-dataplane-v2 --no-enable-master-authorized-networks --addons HorizontalPodAutoscaling,HttpLoadBalancing,GcePersistentDiskCsiDriver --enable-autoupgrade --enable-autorepair --max-surge-upgrade 1 --max-unavailable-upgrade 0 --binauthz-evaluation-mode=DISABLED --enable-managed-prometheus --enable-shielded-nodes --tags \"isolet-node\" --node-locations \"us-central1-c\"\n```\n\nChange the instance configuration of nodes as per your workload requirements\n\n\u003e [!note]\n\u003e Check out [gcloud reference](https://cloud.google.com/sdk/gcloud/reference/container/) for more information\n\n3. Configure `kubectl` to access the cluster\n4. Edit the [challs.json](./api/challenges/challs.json) file according to your challenges\n5. Change the registry variable to your image repository in [update.sh](./update.sh)\n\n```sh\nresource=\"\"\nregistry=\"docker.io/thealpha\"\n```\n\n6. Run the `update.sh` script to build the images\n\n```sh\n./update.sh\n```\n\n7. Update the `image` in the yml files under [definition](./kubernetes/definition/)\n\n```yml\nspec:\n  replicas: 1\n  selector:\n    matchLabels:\n      app: api\n  template:\n    metadata:\n      name: api-deployment\n      labels:\n        app: api\n    spec:\n      containers:\n        - name: api\n          image: docker.io/thealpha16/isolet-api\n          imagePullPolicy: Always\n```\n\n8. Configure the variable according to your requirements. Check out [Configuration](#configuration)\n9. Run the `init.sh` script\n\n```sh\n./init.sh\n```\n\n## Configuration\n\nYou can customize the application using environment variables passed to the deployments. All the options are available in [configuration](/kubernetes/configuration)\n\n### General\n\n- `CTF_NAME` Name of the CTF to be deployed\n\n- `PUBLIC_URL` URL of the deployed application. Required for email verification\n\n- `PROXY_SERVER_NAME` Domains and subdomains to be added under server_name directive in nginx proxy.\n\n\u003e [!note]\n\u003e Check out the nginx documentation for format [server_name](https://nginx.org/en/docs/http/server_names.html)\n\n- `INSTANCE_HOSTNAME` Domain name for accessing the spawned instances\n\n- `IMAGE_REGISTRY` Default registry for pulling challenge images. Can be overridden in the challenge configuration for individual challenges\n\n- `KUBECONFIG_FILE_PATH` Path to the kubernetes config file to access cluster from outside\n\n\u003e [!note]\n\u003e for more information, check out [cluster access](https://kubernetes.io/docs/tasks/access-application-cluster/access-cluster/)\n\n- `UI_URL`\n  host for frontend in case it exists. If kubernetes is being used for deployment, you can specify URL to be\n\n```\n\u003cSERVICE_NAME_OF_UI\u003e.\u003cNAMESPACE\u003e.svc.cluster.local\n```\n\n\u003e [!note]\n\u003e for more information, head over to [dns for pods](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/)\n\n### Instance\n\n- `INSTANCE_NAMESPACE` Namespace for deploying the user requested pods.\n\n- `CONCURRENT_INSTANCES` Number of concurrent pods that user can spawn.\n\n- `TERMINATION_PERIOD`\n  Time in seconds to be given to the pod for graceful shutdown.\n\n- `INSTANCE_TIME` Time in minutes to be added in the pod annotations after which ripper will remove the instance\n\n- `MAX_INSTANCE_TIME` Time in minutes the user can extend the instance\n\n- `CPU_REQUEST` Number of cores to be reserved for the pod\n\n- `CPU_LIMIT` Maximum number of cores the pod can consume\n\n- `MEMORY_REQUEST` Amount of memory to be reserved for the pod\n\n- `MEMORY_LIMIT` Maximum amount of memory the pod can use\n\n- `DISK_REQUEST` Disk space to be reserved for the pod\n\n- `DISK_LIMIT` Maximum disk space the pod can utilize\n\n\u003e [!note]\n\u003e for more information regarding kubernetes resources, check out [resources](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/)\n\n### Secrets\n\n\u003e [!note]\n\u003e Secrets should be base64 encoded\n\n- `SESSION_SECRET` Key used for signing jwt token after login\n\n- `TOKEN_SECRET` Key used for signing verification token sent to mail\n\n- `INSTANCE_NAME_SECRET` Key used for determining unique instance name for the pods\n\n- `EMAIL_ID` Email ID to be used when sending verification mails\n\n- `EMAIL_AUTH` Password for authenticating to use smtp service\n\n- `DB_HOST` Host name of the database server\n\n- `DB_USER` Username for the database\n\n- `DB_PASSWORD` Password to authenticate to the database\n\n- `DB_NAME` Name of the database\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthealpha16%2Fisolet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthealpha16%2Fisolet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthealpha16%2Fisolet/lists"}