mirror of
https://github.com/Ed1s0nZ/CyberStrikeAI.git
synced 2026-10-19 22:17:42 +02:00
Sycun
94a18263b9
The update source used to be three things - a remote name or an address, plus an optional branch - and unset it followed whatever this directory's remotes and upstream happened to say. That asked people to understand git topology before they could update, and the person it was built for could not tell what "follow the remote this tree tracks" meant. It is now one field: config.yaml update.repo, an address, empty meaning the official repository (https://github.com/AIPentest/CyberStrikeAI.git). Point it at a mirror (GitHub is hard to reach in some places) or at your own fork and that is the whole configuration. The branch nothing is any more: an update follows the source repository's own default branch, resolved from the source itself (ls-remote --symref HEAD), so a fork whose default is not "main" still works and nobody has to name a branch. Remote names, the mine/origin/upstream ranking, @{upstream} tracking and the adopt flow's branch argument are all gone with it. The console page loses two input fields: the source section is one address, a hint that empty means the official repository, and a save button; clearing the address is the way back to the default. The install facts drop the remote name, the check section shows the source's default branch once the network answer arrives, and the adopt entry no longer requires saving an address first - the official default makes connecting a tarball install a zero-configuration action. The CLI now reads the same update.repo field the page saves (LoadUpdateRepo reads just that field, without validating the rest of the file - a broken unrelated section must not block the path that fixes the tree), so the keyboard and the button cannot update from different repositories. -check-update prints the source it is about to use. Tests: the source suite now pins the default (official), the single-address save (including the empty-string reset), and that the followed branch comes from the source's own default branch rather than a hardcoded "main"; the console suite posts the one field and renders the default hint; docs, config.example.yaml and upgrade.sh describe the one-field story.
186 lines
8.1 KiB
Markdown
186 lines
8.1 KiB
Markdown
# Deployment Guide
|
|
|
|
[中文](../zh-CN/deployment.md)
|
|
|
|
CyberStrikeAI can run as a local testing tool, an internal team service, or a production red-team platform. Treat it as a high-privilege security system: it can execute commands, call MCP tools, manage WebShell connections, and optionally run C2 listeners.
|
|
|
|
## Prerequisites
|
|
|
|
- Go for source runs and binary builds.
|
|
- Python for some MCP servers and tool scripts.
|
|
- SQLite files under `data/`; no external DB is required by default.
|
|
- Actual security tools installed in PATH. YAML files under `tools/` only describe commands.
|
|
- At least one `ai.channels` entry. Use `provider: openai_compatible` for OpenAI-compatible endpoints, or `provider: claude` for Eino's native Claude component.
|
|
|
|
Important persistent paths:
|
|
|
|
```text
|
|
config.yaml
|
|
data/
|
|
tools/
|
|
roles/
|
|
skills/
|
|
agents/
|
|
knowledge_base/
|
|
chat_uploads/
|
|
```
|
|
|
|
Back these up before upgrades.
|
|
|
|
## Startup Modes
|
|
|
|
Local quick start:
|
|
|
|
```bash
|
|
chmod +x run.sh && ./run.sh
|
|
```
|
|
|
|
`run.sh` is the most common startup path for local use, development, small temporary internal deployments, and quick post-upgrade verification.
|
|
|
|
For long-running service, boot-time startup, managed logs, and crash recovery, prefer a binary managed by systemd.
|
|
|
|
Source run:
|
|
|
|
```bash
|
|
go run ./cmd/server --config config.yaml
|
|
```
|
|
|
|
Binary build:
|
|
|
|
```bash
|
|
go build -o cyberstrike-ai ./cmd/server
|
|
./cyberstrike-ai --config config.yaml
|
|
```
|
|
|
|
The binary still needs `web/templates`, `web/static`, and the runtime resource directories.
|
|
|
|
## HTTPS and Reverse Proxy
|
|
|
|
For local testing, self-signed HTTPS is acceptable:
|
|
|
|
```yaml
|
|
server:
|
|
tls_enabled: true
|
|
tls_auto_self_sign: true
|
|
```
|
|
|
|
For production, use real certificates or terminate TLS at a reverse proxy. If the proxy terminates TLS and forwards HTTP to the app, avoid enabling app-side TLS on the same upstream unless `proxy_pass` uses HTTPS.
|
|
|
|
Nginx must not buffer SSE:
|
|
|
|
```nginx
|
|
proxy_buffering off;
|
|
proxy_http_version 1.1;
|
|
proxy_set_header Upgrade $http_upgrade;
|
|
proxy_set_header Connection "upgrade";
|
|
```
|
|
|
|
## Upgrading
|
|
|
|
**Prefer the platform's own one-click update** (console System settings -> One-click update,
|
|
`POST /api/system/update/apply`, or `./cyberstrike-ai -update` at a keyboard). It pulls the newest
|
|
commit of the **update source repository**'s default branch (the official repository
|
|
`https://github.com/AIPentest/CyberStrikeAI.git` by default; one setting points it at your own fork
|
|
or a mirror): fetch, fast-forward, `go build`, atomic binary swap (the old binary is kept as
|
|
`cyberstrike-ai.prev`), while operator content - `roles/ skills/ tools/ agents/ knowledge_base/
|
|
data/ config.yaml` - is put aside and restored, and the result names every file it kept. When source
|
|
is modified locally or the local history has diverged from the source it refuses and says why
|
|
instead of forcing. See [the developer guide](developer-guide.md) for the full semantics.
|
|
|
|
When a supervisor is detected (systemd/launchd startup markers in the environment), the "exit after
|
|
updating" tick is pre-ticked: the process stands down after a successful update, the supervisor brings
|
|
the new binary back, and the page reloads itself once the service answers (sessions live in memory, so
|
|
one fresh login follows). Forgot the tick, or swapped the binary from the CLI? The console carries a
|
|
persistent banner with **Restart now** - no shell login needed.
|
|
|
|
The update source is a single repository address in the `update` section of `config.yaml` (`repo`),
|
|
or right on the console page: the official repository, your own fork, somebody else's repository or a
|
|
mirror are all just this one setting; empty means the official repository. An installation unpacked
|
|
from a Release archive (no `.git`) can be connected from the same page (no configuration needed - the
|
|
default official repository applies): the preview lists the files the target would replace and the
|
|
operator content that is kept, replaced files are backed up under
|
|
`.update-backup/<timestamp>/overwritten/`, and confirming turns the directory into a normal
|
|
installation with one-click updates.
|
|
|
|
`upgrade.sh` still works and is now a thin shell over that implementation, with two paths decided by
|
|
the installation kind:
|
|
|
|
- **git work tree**: calls `./cyberstrike-ai -update` directly (building
|
|
`go build -o cyberstrike-ai ./cmd/server` first when there is no binary yet, and failing with
|
|
instructions on installing Go when there is neither). `--check` inspects only, through
|
|
`-check-update`.
|
|
- **not a git work tree** (Release tarball install): only here does it fall back to downloading a
|
|
Release tarball and `rsync --delete`-ing it in. The source repository then comes from
|
|
`--repo owner/name` or the `GITHUB_REPO` environment variable, and the built-in default is used only
|
|
when neither is given - with a warning naming which repository the code is coming from.
|
|
`config.yaml`, `data/`, `tools/`, `roles/`, `skills/`, `agents/`, `venv/` (skippable with
|
|
`--no-venv`) and the rollback points `.update-backup/`, `.update-state.json`, `cyberstrike-ai.prev`
|
|
are on the rsync keep list, so `--delete` cannot remove them.
|
|
|
|
Recommended flow either way:
|
|
|
|
1. Stop the service.
|
|
2. Back up `config.yaml`, `data/` and your custom directories.
|
|
3. Pull or replace the new code/binary.
|
|
4. Keep your own configuration and add fields the new `config.yaml` example introduced.
|
|
5. Start the service and check login, model test, tool list and knowledge-base status.
|
|
|
|
The one-click update performs step 3 (plus the rebuild); 1, 2, 4 and 5 stay operator decisions - a
|
|
database migration does not become compatible just because the binary changed. `upgrade.sh` suits
|
|
quick upgrades without compatibility risk; in production still back up first. Python dependencies:
|
|
`venv/` is created and managed by `run.sh`, and keeping it means an upgrade does not remove it - only
|
|
`--no-venv` deletes it and lets `run.sh` reinstall.
|
|
|
|
## Rollback
|
|
|
|
The one-click update leaves its own rollback point: `./cyberstrike-ai -update-rollback`, or the button
|
|
on the page, goes back to the commit before that update and puts `cyberstrike-ai.prev` back. It runs
|
|
only while HEAD is still the commit that update wrote, so work done afterwards is not discarded.
|
|
Content that was put aside also survives under `.update-backup/<timestamp>/`.
|
|
|
|
Beyond that, roll back together:
|
|
|
|
- The previous binary or code.
|
|
- The pre-upgrade `config.yaml`.
|
|
- The pre-upgrade `data/`.
|
|
|
|
If the new version already wrote database schema changes, rolling back the binary alone may not be
|
|
enough; restore the whole backup.
|
|
|
|
## Deployment Decision Table
|
|
|
|
| Scenario | Recommended setup | Key settings | Avoid |
|
|
| --- | --- | --- | --- |
|
|
| Personal testing | `./run.sh` + self-signed HTTPS | `tls_auto_self_sign: true` | Public exposure |
|
|
| Internal team | Binary + systemd + internal HTTPS | strong password, audit, backup, IP restrictions | Shared weak password |
|
|
| Production red-team platform | Reverse proxy + dedicated OS user + log collection | real certs, proxy auth, C2 only when needed | Direct public admin UI |
|
|
| Chat/KB only | Disable C2 and unnecessary MCP | `c2.enabled: false` | All tools enabled by default |
|
|
| Tool automation | Isolated workspace + HITL | `workspace_root_dir`, `hitl`, `monitor` | Shell tools globally allowlisted |
|
|
|
|
## Acceptance Checklist
|
|
|
|
After startup:
|
|
|
|
1. Open `/` and verify no HTTP/HTTPS redirect loop.
|
|
2. Login and validate `/api/auth/validate`.
|
|
3. Run model test in settings.
|
|
4. Check tool list and schemas.
|
|
5. If KB is enabled, check index status.
|
|
6. If external MCP is enabled, verify connection and tool visibility.
|
|
7. If C2 is enabled, start and stop a test listener only in an authorized network.
|
|
8. Check audit logs for login and config activity.
|
|
|
|
## Runtime File Layers
|
|
|
|
- Replaceable: binary, `web/`, default docs/resources.
|
|
- Preserve: `config.yaml`, `data/`, custom tools/roles/skills/agents, `knowledge_base`, uploads.
|
|
- Cleanup candidates: checkpoints, temporary workspaces, stale payloads, old tool execution records.
|
|
|
|
## Source Anchors
|
|
|
|
- App wiring and routes: `internal/app/app.go`
|
|
- TLS bootstrap: `internal/app/main_server_tls.go`
|
|
- HTTP to HTTPS redirect: `internal/app/main_server_http_redirect.go`
|
|
- Config structs: `internal/config/config.go`
|
|
- Config apply: `internal/handler/config.go`
|