{"id":18284483,"url":"https://github.com/samuraiwtf/shogun","last_synced_at":"2026-01-24T12:10:11.135Z","repository":{"id":188513232,"uuid":"678134104","full_name":"SamuraiWTF/shogun","owner":"SamuraiWTF","description":"Utility for deploying multiple container-based lab environments, such as when teaching a class.","archived":false,"fork":false,"pushed_at":"2024-08-11T22:26:14.000Z","size":96,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-05T07:33:30.466Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SamuraiWTF.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2023-08-13T19:43:55.000Z","updated_at":"2024-08-11T22:26:17.000Z","dependencies_parsed_at":"2023-08-15T17:53:47.480Z","dependency_job_id":"b62464d1-35d8-48fb-9034-b0cf81886539","html_url":"https://github.com/SamuraiWTF/shogun","commit_stats":null,"previous_names":["samuraiwtf/shogun"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/SamuraiWTF/shogun","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamuraiWTF%2Fshogun","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamuraiWTF%2Fshogun/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamuraiWTF%2Fshogun/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamuraiWTF%2Fshogun/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SamuraiWTF","download_url":"https://codeload.github.com/SamuraiWTF/shogun/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamuraiWTF%2Fshogun/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28727391,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-24T10:24:43.181Z","status":"ssl_error","status_checked_at":"2026-01-24T10:24:36.112Z","response_time":89,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2024-11-05T13:13:42.309Z","updated_at":"2026-01-24T12:10:11.121Z","avatar_url":"https://github.com/SamuraiWTF.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Shogun - The boss of student labs\n\nThis project is designed for creating student labs using Docker and Nginx. It provides a convenient way to manage lab environments for students by creating, listing, and deleting student containers and lab configurations.\n\n## Prerequisites:\n1. Python (already installed)\n2. Nginx\n\n## Initial Installation:\n\n1. Install pipenv:\n   Open a terminal and run the following command to install pipenv:\n   ```\n   pip install pipenv\n   ```\n\n2. Set up pipenv:\n   In the project directory, run the following command to install the required dependencies:\n   ```\n   pipenv install\n   ```\n\n3. Nginx configuration:\n   Make sure Nginx is installed on your system. Update your nginx.conf file with the following content:\n   ```\n   worker_processes  1;\n\n   events {\n       worker_connections  1024;\n   }\n\n   http {\n       include       mime.types;\n       default_type  application/octet-stream;\n\n       sendfile        on;\n       keepalive_timeout  65;\n       server_names_hash_bucket_size 64;\n\n       # Include server blocks configuration for labs\n       include shogun.conf;\n   }\n   ```\n   \n4. Setting up SSL with Nginx (Optional):\n\nShogun can be configured to automatically generate certificates by using a certificate provider.  The following providers are supported:\n\n- NONE: No SSL certificates will be generated.  This is the default.\n- SELF_SIGNED: Self-signed certificates will be generated automatically.\n\nTo configure the certificate provider, set the `CERT_PROVIDER` environment variable to the desired provider. This can be done in the `.env` file or by setting the environment variable directly.\n\nFor example, to use self-signed certificates, set the following environment variable:\n```\nCERT_PROVIDER=SELF_SIGNED\n```\n\n**Modify the Nginx Configuration:**\n\nEnvironment Variables:\n\nAdjust your `.env` file to include relevant SSL related variables:\n\n```\nROOT_DOMAIN=example.com\n```\nUse the actual root domain for your lab environment.\n\n5. Handling URLs that don't match a lab:\n\nIt is recommended that you handle URLs that don't match any lab environment by responding with an error message. This can be accomplished in your main nginx.conf file by adding instructions such as:\n\n```nginx\nserver {\n    listen       80 default_server;\n    server_name  _;\n    location / {\n        return 200 '\u003chtml\u003e\u003chead\u003e\u003ctitle\u003eError\u003c/title\u003e\u003c/head\u003e\u003cbody\u003e\u003ch1\u003eInvalid URL\u003c/h1\u003e\u003cp\u003ePlease check the URL and try again.\u003c/p\u003e\u003c/body\u003e\u003c/html\u003e';\n        add_header Content-Type text/html;\n    }\n}\n\nserver {\n    listen       443 ssl default_server;\n    server_name  _;\n\n    ssl_certificate     /path/to/your/certificate.crt;\n    ssl_certificate_key /path/to/your/private.key;\n\n    location / {\n        return 200 '\u003chtml\u003e\u003chead\u003e\u003ctitle\u003eError\u003c/title\u003e\u003c/head\u003e\u003cbody\u003e\u003ch1\u003eInvalid URL\u003c/h1\u003e\u003cp\u003ePlease check the URL and try again.\u003c/p\u003e\u003c/body\u003e\u003c/html\u003e';\n        add_header Content-Type text/html;\n    }\n}\n```\nBoth of these should go right before your `include shogun.conf;` line.\n\n6. Restricting access by X-SAMURAIWTF header (optional)\n\nIf you are hosting your labs on the Internet, you may want to use this measure to protect the labs from unauthorized access.  This is not a foolproof method, but it will prevent most automated scanners from accessing your labs.\n\nTo enable this feature, set the `X_SAMURAIWTF` environment variable to a random string.  This can be done in the `.env` file or by setting the environment variable directly.\n\nThe distribute this string to your students so they can use it to access the labs. The students will need to set up a rule in their proxy tool to add the `X-SAMURAIWTF` header to all requests.\n\n## CLI Usage:\n\nYou can use the provided shogun.bat (for Windows) or shogun shell script (for Unix systems) to interact with the CLI. The available commands are:\n\n1. Create a new student container:\n   ```\n   shogun create \u003cstudent_id\u003e \u003clab_id\u003e [--count \u003ccount\u003e] [--start \u003cstart\u003e] [--norestart]\n   ```\n\n2. Delete a student container:\n   ```\n   shogun delete [\u003cstudent_id\u003e] [\u003clab_id\u003e] [--norestart]\n   ```\n\n3. List available or active labs:\n   ```\n   shogun list \u003ctype\u003e\n   ```\n\nFor detailed information about each command and its arguments, run:\n   ```\n   shogun --help\n   ```\n\n---\n\n## Adding a New Lab to Shogun\n\nTo integrate a new lab into the Shogun platform, you must follow a structured approach that ensures smooth deployment and management. Here's a step-by-step guide on how to add a new lab:\n\n### 1. Prepare the Lab Project\n\nIf your lab project already builds Docker images to a public repo (such as Dockerhub), you can skip this step. Otherwise, you'll need to set up a GitHub repository for your lab and configure GitHub Actions to build and push Docker images to a container registry. Here are the recommended steps for doing this with GitHub Actions:\n\n#### a. Organizing Dockerfiles\n\nInside your lab's repository, create a directory named `.shogun`. This directory will house all Dockerfiles tailored for Shogun deployment.\n\nExample structure:\n\n```\n- your_lab_name/\n    - src/\n    - docker-compose.yml\n    - .shogun/\n        - Dockerfile.service1\n        - Dockerfile.service2\n        ...\n```\n\nEach Dockerfile within the `.shogun` directory corresponds to a specific service in your lab. Name them appropriately so that their purpose is clear.\n\n#### b. Locally Testing the New Dockerfile(s)\n\nBefore proceeding to set up GitHub Actions, it's important to test the new Dockerfiles locally to make sure they are working as indended. Here's how we can test each Dockerfile:\n\n1. Build the Docker image locally:\n   ```\n   docker build -t your_lab_name_service1 -f .shogun/Dockerfile.service1 .\n   ```\n2. Run the Docker image locally:\n   ```\n   docker run -d --name your_lab_name_service1 -p 8080:80 your_lab_name_service1\n   ```\n3. Test the service by visiting `localhost:8080` in your browser.\n4. Check the logs to ensure there are no errors:\n   ```\n   docker logs your_lab_name_service1\n   ```\n5. Stop and remove the container:\n   ```\n    docker stop your_lab_name_service1\n    docker rm your_lab_name_service1\n    ```\n\n**Note:** If your container is being hosted as a GitHub package, make sure you [connect a repository to the package](https://docs.github.com/en/packages/learn-github-packages/connecting-a-repository-to-a-package) by adding the source label (e.g. `LABEL org.opencontainers.image.source=https://github.com/OWNER/REPONAME`) instruction to your Dockerfile.\n\nView the [dojo-basic](https://github.com/SamuraiWTF/samurai-dojo) repository for an example of how to set up a GitHub package for a lab and the actions required to build and push Docker images to the package.\n\n#### c. GitHub Actions\n\nSet up GitHub Actions to automatically build Docker images from the Dockerfiles in `.shogun` and push them to a container registry. Ensure the image names and tags are predictable and consistent across labs, e.g., `ghcr.io/username/your_lab_name_service1:latest`.\n\n\n\n\n### 2. Docker Compose Template for Shogun\n\n#### a. Template Creation\n\nCreate a Docker Compose template for your lab, similar to how you'd set up a standard Docker Compose file, but with placeholders that Shogun will replace during deployment (e.g., `{{ student_id }}`, `{{ lab_id }}`).\n\n#### b. Required Labels\n\nAll services in your compose template should include specific labels to ensure they're appropriately managed by Shogun:\n\n```yaml\nlabels:\n  - 'lab_id={{ lab_id }}'\n  - 'student_id={{ student_id }}'\n```\n\nFor example:\n\n```yaml\nversion: '3'\nservices:\n  web:\n    image: 'ghcr.io/username/your_lab_name_service1:latest'\n    container_name: '{{ student_id }}_{{ lab_id }}_web'\n    ports:\n      - '{{ web_host_port }}:80'\n    labels:\n      - 'lab_id={{ lab_id }}'\n      - 'student_id={{ student_id }}'\n```\n\n#### c. Adding Template to Shogun\n\nOnce your Docker Compose template is ready, add it to the Shogun project under:\n\n```\nshogun/lab_configs/docker_compose_templates/your_lab_name.template.yml\n```\n\n### 3. Update Shogun's Lab List\n\nEnsure you update any central list or configuration within Shogun that keeps track of available labs. By default this is the lab_configs/default_config.yaml file but you can also create your own configuration file. To specify a custom config file, add a `CONFIG_FILE` entry to your .env file:\n\n```\nCONFIG_FILE=your_config_file.yaml\n```\n\n## Tools and Scripts\n\n### docker_peak_mem.sh\nThis bash script keeps track of the maximum memory usage of all running containers. It uses `docker stats` to accomplish this. This is intended to help determine the necessary memory requirements for a lab server while testing new container builds.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamuraiwtf%2Fshogun","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamuraiwtf%2Fshogun","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamuraiwtf%2Fshogun/lists"}