Merge pull request #40 from Jacute/dev

v0.2.0

Author: Jacute

.env

@@ -0,0 +1,61 @@
+name: tests
+
+on:
+  push:
+    branches: [ "**" ]
+  pull_request:
+    branches: [ master, dev ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.25.3'
+
+      - name: Build jacfarm-api
+        run: cd ./jacfarm-api && go build -v ./...
+      
+      - name: Build config_loader
+        run: cd ./workers/config_loader && go build -v ./...
+      
+      - name: Build exploit-runner
+        run: cd ./workers/exploit_runner && go build -v ./...
+      
+      - name: Build flag-sender
+        run: cd ./workers/flag_sender && go build -v ./...
+
+  tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.25.3'
+      
+      - name: Install gocovmerge
+        run: go install github.com/wadey/gocovmerge@latest
+
+      - name: Run tests on jacfarm-api
+        run: make coverage
+
+      # --- Upload to Codecov ---
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: Jacute/JacFARM
+          files: coverage.out
+
+      # --- Upload to Coveralls ---
+      - name: Upload coverage to Coveralls
+        uses: coverallsapp/github-action@v2
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          path-to-lcov: coverage.out

.github/workflows/tests.yml

@@ -2,4 +2,6 @@ todo
 database.db
 error_writer
 coverage.html
-volumes
+volumes
+backend.sh
+.env

.gitignore

@@ -1,3 +1,5 @@
+.PHONY: help up down clean-db clean-all reset coverage
+
 # Цвета
 GREEN  := \033[0;32m
 PURPLE := \033[0;35m
@@ -18,13 +20,26 @@ up: ## Start services
 	@echo "$(GREEN)[$(PURPLE)start$(GREEN)]$(RED) Starting services$(RESET)"
 	@mkdir -p volumes/exploits
 	@sudo chown -R 1000:1000 ./volumes/exploits
-	@echo "JACFARM_API_KEY=$(JACFARM_API_KEY)" > .env
-	@echo "ADMIN_PASS=$(ADMIN_PASS)" >> .env
-	@echo "$(PURPLE)Farm api key$(RESET) - $(JACFARM_API_KEY)"
-	@echo "$(PURPLE)Farm admin creds$(RESET) - admin:$(ADMIN_PASS)"
+	@touch .env
+
+	@if grep -q '^JACFARM_API_KEY=' .env; then \
+		printf "$(PURPLE)Farm api key$(RESET) - %s\n" "$$(grep '^JACFARM_API_KEY=' .env | cut -d'=' -f2-)"; \
+	else \
+		echo "JACFARM_API_KEY=$(JACFARM_API_KEY)" >> .env; \
+		printf "$(PURPLE)Farm api key$(RESET) - %s\n" "$(JACFARM_API_KEY)"; \
+	fi
+
+	@if grep -q '^ADMIN_PASS=' .env; then \
+		printf "$(PURPLE)Farm creds$(RESET) - admin:%s\n" "$$(grep '^ADMIN_PASS=' .env | cut -d'=' -f2-)"; \
+	else \
+		echo "ADMIN_PASS=$(ADMIN_PASS)" >> .env; \
+		printf "$(PURPLE)Farm creds$(RESET) - admin:%s\n" "$(ADMIN_PASS)"; \
+	fi
+
 	@sudo docker compose --env-file .env up --build -d
 	@echo "$(GREEN)Services started$(RESET)"
 
+
 down: ## Stop services
 	@echo "$(GREEN)[$(PURPLE)stop$(GREEN)]$(RED) Stopping services$(RESET)"
 	@sudo docker compose down
@@ -39,3 +54,37 @@ clean-all: ## Remove all volumes (db, rabbitmq, exploits)
 	@rm .env
 
 reset: down clean-all up ## Full reset: stop, clean and restart
+
+coverage:
+	@echo "$(GREEN)Running tests$(RESET)"
+	
+	@cd jacfarm-api && \
+	PKGS=$$(go list ./... | grep -vE 'mocks|cmd/jacfarm-api' || true) && \
+	if [ -z "$$PKGS" ]; then echo "No packages found in jacfarm-api"; exit 0; fi && \
+	CSV=$$(echo $$PKGS | tr ' ' ',') && \
+	echo "Running go test for: $$PKGS" && \
+	go test -v -race -coverpkg=$$CSV -covermode=atomic -coverprofile=../jacfarm-api.out $$PKGS
+
+	@cd workers/config_loader && \
+	PKGS=$$(go list ./... | grep -vE 'mocks|cmd/config_loader' || true) && \
+	if [ -z "$$PKGS" ]; then echo "No packages found in config_loader"; exit 0; fi && \
+	CSV=$$(echo $$PKGS | tr ' ' ',') && \
+	echo "Running go test for: $$PKGS" && \
+	go test -v -race -coverpkg=$$CSV -covermode=atomic -coverprofile=../../config_loader.out $$PKGS
+
+	@cd workers/exploit_runner && \
+	PKGS=$$(go list ./... | grep -vE 'mocks|cmd/exploit_runner' || true) && \
+	if [ -z "$$PKGS" ]; then echo "No packages found in exploit_runner"; exit 0; fi && \
+	CSV=$$(echo $$PKGS | tr ' ' ',') && \
+	echo "Running go test for: $$PKGS" && \
+	go test -v -race -coverpkg=$$CSV -covermode=atomic -coverprofile=../../exploit_runner.out $$PKGS
+	
+	@cd workers/flag_sender && \
+	PKGS=$$(go list ./... | grep -vE 'mocks|cmd/flag_sender' || true) && \
+	if [ -z "$$PKGS" ]; then echo "No packages found in flag_sender"; exit 0; fi && \
+	CSV=$$(echo $$PKGS | tr ' ' ',') && \
+	echo "Running go test for: $$PKGS" && \
+	go test -v -race -coverpkg=$$CSV -covermode=atomic -coverprofile=../../flag_sender.out $$PKGS
+	
+	gocovmerge jacfarm-api.out config_loader.out exploit_runner.out flag_sender.out > coverage.out
+	rm exploit_runner.out flag_sender.out jacfarm-api.out config_loader.out

Makefile

@@ -1,12 +1,79 @@
 # JacFARM
 
-Exploit farm for attack-defense CTF competition
+<p align="center">
+  <picture>
+    <img alt="JacFARM Logo" src="https://raw.githubusercontent.com/Jacute/JacFARM/refs/heads/master/docs/logo.png" width="300">
+  </picture>
+</p>
+<p align="center">
+  <strong>Exploit farm for attack-defense CTF competition</strong>
+</p>
+<p align="center">
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#features">Features</a> •
+  <a href="#components">Components</a>
+</p>
+<p align="center">
+  <a href="https://github.com/Jacute/JacFARM/actions"><img src="https://github.com/Jacute/JacFARM/actions/workflows/tests.yml/badge.svg" alt="CI Status"></a>
+  <a href="https://codecov.io/gh/ollelogdahl/concord"><img alt="Codecov" src="https://codecov.io/gh/Jacute/JacFARM/master/master/graph/badge.svg"></a>
+  <a href="#"><img alt="Coveralls" src="https://coveralls.io/repos/github/Jacute/JacFARM/badge.svg?branch=master"></a>
+  <a href="https://github.com/Jacute/JacFARM/releases"><img alt="Release" src="https://img.shields.io/github/v/release/Jacute/JacFARM"></a>
+</p>
+
+## Quick start
+
+### Dependencies
+
+- Docker
+- Docker Compose
+- Make
+
+### Start
+
+1. Configure *config.yml* for your competition. A detailed description of the quick configuration is [here](./docs/config.md)
+
+2. Start the farm
+```bash
+make up
+```
+
+Credentials for basic auth and the token for sending flags via start_exploit.py will be printed to stdout.
+
+3. After the game ends, turn off the farm and clean the database and queue
+```bash
+make down
+make clean-all
+```
+
+## Features
+
+- Uploading exploits in ui
+- Real-time configuration farm options like number of concurrently running exploits, the size of the flag sending batch, team ip addresses, etc
+- The ability to [change the plugin for sending flags to jury](./docs/flag_sender/flag_sender.md).
+- There are already two sending plugins: [forcad_http](./workers/flag_sender/plugins/forcad_http/client.go) and [saarctf_tcp](./workers/flag_sender/plugins/saarctf_tcp/client.go).
+- Different [exploit types](./docs/exploit_runner/exploit_runner.md):
+  - Python (one file)
+  - Python (zip)
+  - Bash script
+  - Binary
+- View logs of running exploits and sending flags on ui
+- Configuring vulnboxes ip addresses using [various methods](./docs/config.md)
 
 ## Components
 
-### Arch Diagram
+### Client
+
+- **Frontend** - ui for
+  - viewing flags with any filters
+  - adding exploits of different types via '+' button
+  - deleting or updating exploits by right mouse button
+  - adding teams
+  - updating farm config
+  - viewing logs
+
+![](./docs/img/frontend.png)
 
-![](./docs/img/diagram.jpg)
+- **start_exploit.py** - python cli tool for starting exploits on local machine (TODO)
 
 ### Server
 
@@ -15,8 +82,14 @@ Exploit farm for attack-defense CTF competition
 - **JacFARM API** - API for frontend and cli start_exploit.py.
 - **Config Loader** - loads config into db from config.yml on start. Next configuration editing is available through the frontend.
 
-### Client
+#### Plugins
 
-- **start_exploit.py** - python cli tool for starting exploits on local machine (TODO)
-- **Frontend**
-![](./docs/img/frontend.png)
+**Plugin** - is a function in a farm that sends flags to the jury system.
+
+⚠️ Farm contains two plugins for [ForcAD](https://github.com/pomo-mondreganto/ForcAD) and saarCTF jury systems. If you write plugins for other jury systems, you can create a pull request to add them into repository.
+
+[Plugin example for ForcAD](./workers/flag_sender/plugins/forcad_http/client.go)
+
+### Arch Diagram
+
+![](./docs/img/diagram.jpg)

README.md

@@ -3,6 +3,19 @@ exploit_runner:
     - 10.10.1.2
     - 10.10.2.2
     - 10.10.3.2
+  team_ip_cidrs:
+    - "10.228.79.0/24"
+    - "10.229.79.0/24"
+  team_ip_ranges:
+    - "10.200.78.2-10.200.78.200"
+    - "10.200.78.221-10.200.78.233"
+  team_ip_from_N: # N - range(n_start, n_end); X = N / block + offset_x, Y = N % block + offset_y
+    n_start: 0
+    n_end: 2000
+    offset_x: 32
+    offset_y: 0
+    block: 200
+    ip_template: "10.{X}.{Y}.2"
   flag_format: '[A-Z0-9]{31}='
   run_duration: 10s
   exploit_directory: ./exploits
@@ -15,7 +28,7 @@ flag_sender:
   jury_flag_url_or_host: http://10.10.10.10/flags # url for http, host for tcp
   token: asd123
   flag_ttl: 5m
-  submit_timeout: 10s
+  submit_timeout: 30s
   submit_period: 5s
   submit_limit: 50
   plugin_directory: ./plugins