Flocks User Manual

This manual is distilled from the full Flocks online documentation. It is intended for users who need an offline reference when the docs site is not convenient to access.
Installation, startup, and first-time configuration are covered in Quick Start. This page keeps offline navigation and core scenario guidance.

---

Contents

1. Product Overview
2. Quick Start: Installation / Startup / First-Time Configuration
3. Main Module Guide
4. Model Configuration
5. Communication and Remote Deployment
6. Messaging & Alerting Integrations: Feishu / WeCom / Slack / WeChat / WhatsApp / DingTalk / Telegram / Email Integration
7. Operations and Troubleshooting
8. Upgrade Methods
9. Security and Compliance
10. Scenario Walkthroughs
    • 10.1 Alert Triage
    • 10.2 Host Forensics
    • 10.3 Network Security Product Integration
    • 10.4 Browser Automation and Web Login
    • 10.5 Threat Intelligence and IOC Triage
    • 10.6 Internet Asset Discovery
11. CLI Command Reference
12. Configuration Index
13. Glossary

---

1. Product Overview

Flocks is an agent-powered platform for security operations. It is not a simple chat assistant or an automation engine that only runs fixed rules. It brings conversation, analysis, execution, orchestration, integration, knowledge capture, and continuous operations into one platform.

Use Cases

• Security operations teams that need multi-source correlation and first-pass alert triage
• Teams that need to turn investigation steps into workflows, Skills, or expert Agents
• Environments that need to connect multiple security devices, APIs, web consoles, or internal systems
• Teams that want to turn one-off analysis into continuous operational workflows

Core Capabilities: Five Layers

Layer	Purpose	User-facing capabilities
Multi-entry access layer	Provides different interaction methods	WebUI, CLI, TUI, channels
Platform service layer	Unifies the backend and management plane	Sessions, models, tools, workflows, Skills, tasks, Workspace, channels
Agent runtime layer	Keeps tasks moving forward	Session loop, tool calls, summary compression, result merging
Capability extension layer	Hosts extensible capabilities	tools / workflows / agents / skills / MCP / plugins
Platform support layer	Provides governance and knowledge retention	Configuration, memory, Workspace, Task Center, persistence

The platform uses the main Agent Rex as the unified entry point. Its foundation includes the session runtime, tool system, workflow engine, expert Agents, Skills, memory system, task scheduling, and multi-entry access.

---

2. Quick Start

2.1 Installation / Startup / First-Time Configuration

This manual does not repeat the details of installation and first-time configuration. Use the following entry points:

• Installation, startup, and model configuration: Quick Start
• Access control and remote deployment: Deployment and Configuration
• Operations and troubleshooting: Operations and Troubleshooting

2.2 Suggested Task Order

• First-time users: start with installation options and prerequisites
• Local interaction first: use the one-line command path in Quick Start
• Server or standardized deployment: start with the Docker path in Quick Start
• Get it running before exploring: return to Feature Modules and Scenario Practices

---

3. Main Module Guide

WebUI navigation is divided into three groups: Home / AI Workbench (sessions, Task Center, Workspace) / Agent Studio (Agent, Workflow, Skills, tool list, model list, channels).

3.1 Conversation Management

The main interaction surface in Flocks. Describe your goal directly to Rex; the platform understands context, calls tools, runs workflows, and delegates work to expert Agents.

Best for: goals that are clear but do not map to an obvious capability; analysis that needs follow-up questions; tasks where Rex should understand first and coordinate afterward.

3.2 Agent

Manage the main Agent (Rex) and sub-agents for intelligence analysis, host investigation, vulnerability analysis, web data extraction, and more. Best for: specialized execution roles for recurring task types; capturing mature investigation playbooks; separating command and execution.

3.3 Workflow

Organize actions into stable processes. Workflows are automation playbooks that can be created, validated, tested, and run. Best for: standardized handling of fixed alert types; periodic inspection, reporting, and scheduled tasks; multi-step processes that require clear nodes and I/O.

3.4 Task Center

Long-running and scheduled execution. It extends one-time actions into continuous operations. Relationship: Workflow defines the process · Agent decides the role · Task Center runs it on schedule.

3.5 Workspace

A project-level boundary that contains plugins, workflows, Skills, configuration, task outputs, and project context. It is suitable for team-based, multi-project, and multi-customer work.

3.6 Tool List

Execution capabilities that the platform can call directly, including built-in tools, API tools, local tools, and MCP.

In the current WebUI, MCP has been integrated into the tool list and no longer has a separate top-level page.

3.7 Model List

Providers, models, default model, and test entry points. When functionality is abnormal, check here first: whether model testing passes, whether a default model is set, and whether Base URL / API Key / model name are consistent.

3.8 Skills Library

Hosts methodologies, standards, task templates, and organizational experience. Four capability boundaries: tools focus on actions · Workflow focuses on processes · Agent focuses on roles · Skills focus on experience / methods.

3.9 How Modules Work Together

Configure the default model in the model list
    ↓
State your goal to Rex in a session
    ↓
Rex calls tools / delegates to Agents / generates a Workflow
    ↓
Task Center turns a one-time capability into scheduled operations
    ↓
Skills and Workspace retain experience and project assets

---

4. Model Configuration

4.1 Model Configuration Order

Add Provider → add model → test connection → set default model.

4.2 Local / Third-Party Model Integration

Main path: OpenAI Compatible. This applies to self-hosted services compatible with the OpenAI API, third-party gateways, and local model services.

Key fields: Base URL, API Key, and model name. Any mismatch can cause issues such as no model list, 404, a port that appears not to take effect, or simple conversations working while complex tasks remain unstable.

"Supports a model" does not mean every deployment is fully compatible, that the model list can always be fetched automatically, or that complex multi-turn tasks are always stable. Real task stability must be tested.

4.3 Troubleshooting Model Errors

Error	Possible cause
Timeout	Model platform load, network path, or responses slower than the system expects
empty content	Model platform or compatibility-layer issue
peer closed connection	Interrupted connection or abnormal server-side disconnect

Troubleshooting order: retest → check backend logs → distinguish whether all models fail or only one model fails → compare with a known stable model → test in long sessions / tool calls / long-output scenarios.

4.4 Runtime Configuration Domains: flocks.json

Configuration domain	What it solves
provider	Where models come from
api_services	Which external security capabilities are connected, such as greynoise, threatbook, skyeye, qingteng, tdp
mcp	How external context services are connected uniformly
channels	Where results are sent
sandbox	Where execution boundaries are set

---

5. Communication and Remote Deployment

By default, Flocks listens on 127.0.0.1, so it is accessible only from the local machine. Remote access requires explicitly changing the listening address.

5.1 Recommended Remote Deployment Method

flocks start --host <internal_ip>

When you need to listen on all network interfaces, use flocks start --host 0.0.0.0. In this mode, restrict access with firewalls, security groups, reverse proxies, and TLS.

5.2 Remote Access with Docker

Confirm that the -p 5173:5173 port mapping is correct. If the container runs but the WebUI is unreachable, check the port mapping and firewall rules first.

5.3 Common Misconceptions

1. Assuming the default 127.0.0.1 can also be accessed by external machines ❌
2. Continuing to expose the old 8000 port from earlier versions instead of routing API requests through /api under 5173 ❌

5.4 Restricted Networks / Mainland China Recommendations

• Use the Gitee installation entry point
• Configure a domestic mirror for uv, such as the Tsinghua mirror
• Use a domestic Docker image address, such as ghcr.nju.edu.cn/agentflocks/flocks:latest

uv mirror example, saved to ~/.config/uv/uv.toml:

[[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"

[[index]]
url = "https://pypi.org/simple"
default = true

5.5 Relationship Between WebUI and API

• The WebUI and API are served from the same address and port, defaulting to 127.0.0.1:5173
• API requests are routed through the /api endpoint on the same host and port
• Programmatic API clients must include an API Token

---

6. Messaging & Alerting Integrations

Currently supported channels: Feishu / WeCom / Slack / WeChat / WhatsApp / DingTalk / Telegram / Email Integration.

6.1 Use Cases

• Proactively push triage results to WeCom / Slack / WeChat / WhatsApp / DingTalk / Telegram sessions or mailboxes
• Let bots receive messages in specific groups, sessions, or email threads
• Push scheduled task results to on-call or operations teams

6.2 Capability Flow

Agent analysis and execution -> Workflow process orchestration -> Task Center scheduling -> channels deliver to external touchpoints

6.3 Integration Essentials

• DingTalk: internal enterprise application + bot + group verification
• Feishu: self-built app in the open platform + permissions + App ID / App Secret
• WeCom: admin console + intelligent bot + Bot ID / Secret. Multi-group delivery and Session ID details are covered on the WeCom page
• Slack: Slack App + Socket Mode + Bot Token / App Token
• WeChat: scan the QR code in WebUI to log in to iLink Bot and automatically obtain Token / Account ID
• WhatsApp: pair through Linked Devices in the WebUI by scanning a QR code
• Email Integration: dedicated mailbox + IMAP receiving + SMTP replies + sender allowlist

6.4 Recommended Flow

Data enters Flocks through API / logs / web scraping
    ↓
Agent or Workflow analysis
    ↓
Send results through channels such as WeCom / Slack / WeChat / WhatsApp / DingTalk / Telegram / Email Integration

---

7. Operations and Troubleshooting

7.1 Start With Logs

flocks logs

For deeper diagnosis, check ~/.flocks/logs/backend.log.

Where to look for artifacts: current workspace / session output directory, ~/.flocks, Docker mount directory, and Workflow artifacts.

Common reasons for "the report was saved but I cannot find it": the artifact is in the workspace or mounted directory, you are checking a different runtime directory, or Docker files are not mapped to the host.

7.2 Check the Task Center Before Logs

For scheduled tasks / batch analysis / Workflow scenarios, check Task Center first to see whether it ran and which step it reached, then check logs to understand why it failed.

7.3 Installation Troubleshooting Order

1. Check base dependencies: uv, Node.js 22+, npm, agent-browser
2. Confirm that the installation script ran completely
3. Confirm that the flocks command is available
4. Decide whether to switch installation methods

7.4 Common Installation Issues

Symptom	Action
Node.js / npm installation fails, frontend build fails	Manually install a supported version and retry
flocks command is unavailable	Re-enter the source directory and rerun the installation script
Browser dependency fails	This may affect the entire installation chain; do not treat it only as a browser-feature issue

7.5 Platform Compatibility

• Linux / macOS: closest to the official main path
• Windows: depends on administrator privileges and has more environment issues
• WSL: prone to Node / update-path issues
• ARM: Docker is recommended first

7.6 When to Switch Installation Methods

• Full interaction + web login required → local terminal / source installation
• One-click installation fails repeatedly → source installation
• Fewer Windows pitfalls → source / Docker
• Standardized server deployment → Docker

---

8. Upgrade Methods

8.1 Comparing Three Methods

Method	Best for
One-click page upgrade	Linux / macOS, no known compatibility issues, standard installation method
Manual source upgrade	The most reliable path when page upgrade fails
Docker image upgrade	Standardized operations

8.2 Manual Source Upgrade

flocks stop
git pull
./scripts/install.sh
flocks restart

For Windows, use install.ps1 in administrator PowerShell.

8.3 Docker Upgrade

Pull the new image → rebuild / restart the container → confirm that mounted directories are preserved.

8.4 Handling Upgrade Issues

Symptom	Possible cause
Upgrade stays stuck for a long time	Treat long periods without new output as failure and switch to manual upgrade
Page still says an upgrade is available	Cache / version marker / old problematic version crossed during upgrade
Listening address returns to default	Upgrade crossed an old service model, runtime state was lost, or an old process did not exit cleanly
Page opens but features are abnormal	Default model was not restored / frontend cache / upgrade incomplete / old process still running

Recovery order: flocks status → flocks logs → confirm that old processes have exited → if necessary, run flocks restart --host <host_ip> --port <port> → check the default model and channels.

---

9. Security and Compliance

9.1 Public Exposure

Local-only execution is the default security boundary. Recommended exposure strategy:

• Expose only the unified service port, not the old backend port
• Restrict access with security groups / firewalls / reverse proxies
• Protect remote access with TLS, account login, and API Token

Minimum pre-deployment check: whether internet access is truly needed, whether only required ports are open, whether an allowlist / trusted network segment is in place, and whether access is consolidated through a reverse proxy.

9.2 Data and Desensitization Principles

• Prefer intranet / private models for highly sensitive data
• For public models, review your organization's outbound data policy first
• Decide whether raw logs / original alert text / sample content should be preprocessed first

Use special caution with: account tokens, passwords, and keys; attack samples / malicious payloads; large volumes of internal asset information; compliance-restricted data.

Flocks is best treated as an analysis and orchestration platform. It does not assume all data governance responsibilities by default. Secure production use requires a combined design across model deployment location, network boundaries, logging standards, and compliance requirements.

9.3 Feedback Channels

• General issues such as documentation, experience, or ordinary feature problems → official repository Issues and community
• Security issues such as suspected vulnerabilities, unauthorized-access risk, or sensitive-data boundaries → official security feedback channel / product team / designated contact

If you suspect an historical version is involved: check official announcements to confirm the affected scope → check deployment time and version → then decide whether to upgrade, roll back, or add compensating controls.

---

10. Scenario Walkthroughs

Six reusable scenarios are available. Each scenario follows overview / inputs and outputs / prerequisites / steps / real case walkthrough / output example / continuous operation / boundaries, so you can follow the pattern directly.

Recommended first implementations: alert triage and host inspection are usually the first two Flocks scenarios that work in enterprises. New users should start with these two paths.

Common Product Pattern

1. Rex understands the task            → breaks it into steps and selects capabilities
2. Schedules expert Agents / tools / Workflow → executes actions
3. Writes intermediate data + structured output → more than an answer in a chat
4. Channel notifications + scheduled tasks → upgrades "run once" into "routine operations"
5. Captures experience as a Skill      → reuse it directly for similar tasks next time

---

10.1 Alert Triage

The easiest Flocks scenario to implement and the one used most often. Core question: after alerts are received from security devices, how can each one get a structured conclusion with an evidence chain within minutes and be pushed automatically to operations touchpoints?

Inputs / Outputs

• Input: a single alert ID / raw alert, a batch of alerts to triage, or alerts in a time window; sources can include TDP / NDR / XDR / HIDS / EDR / WAF
• Output: structured triage result, including alert ID, attack type, confidence, affected assets, and recommended action; JSON report; WeCom / DingTalk / Feishu notification

Prerequisites

Dependency	Requirement
Model	Default model available; reasoning models work better
Alert source	Either API or web console
Tools	Intelligence tools such as ThreatBook / VT / GreyNoise for IOC context enrichment
Channel	At least one of WeCom / DingTalk / Feishu connected
Expert Agent	Optional; an alert-analysis sub-agent is built in, otherwise Rex analyzes directly

Steps in WebUI

1. Create a session: create a new session and describe the goal in natural language, for example:

   "Fetch the five latest alerts from the TDP page, triage them one by one, write the results as JSON, and send the summary to WeCom"

2. Rex fetches raw data: call the API directly if available; otherwise use browser login and extraction. Raw alerts are written to the Workspace date directory, such as 3-28/alerts.json; this is what allows scheduled tasks to reuse them
3. Delegate per-alert analysis to an Agent: Rex handles slicing, dispatch, and aggregation. Each sub-agent analyzes one alert independently, keeping contexts separate
4. Write JSON + send channel notification: results are written back to Workspace, and a summary is sent through the channel

   In multi-group environments, explicitly specify the Session ID

5. Turn it into a scheduled task:

   "Configure this inspection and triage process as a scheduled task that runs once every hour and sends results to WeCom"

   Rex automatically creates a task in Task Center: hourly execution / reuse this natural-language description / specify channel and Session ID

Real Case Walkthrough: Five NDR Alerts, About Four Minutes

Time	Rex action
0:00	Confirms the WeCom bot and target Session ID are configured
0:36	Fetches five alerts from the TDP page
1:03	Writes complete raw data to the Workspace 3-28 directory
1:33	Delegates analysis to the dedicated alert-analysis sub-agent
2:04	Analysis results take shape with structured fields and conclusions
2:22	Pushes a notification to WeCom
2:42	Identifies "file upload attack x4", "IP 109.x recurring", and "WebShell + internal lateral movement"
3:42	Converts the whole process into an hourly scheduled task with WeCom notification

Output Example

[
  {
    "alert_id": "20260328-001",
    "source": "TDP",
    "attack_type": "webshell_upload",
    "src_ip": "109.x.x.x",
    "dst_asset": "10.10.x.x",
    "confidence": 0.85,
    "conclusion": "Confirmed file upload attack; WebShell implantation is possible",
    "related_alerts": ["20260328-003"],
    "recommended_action": "Isolate the asset + preserve evidence"
  }
]

Boundaries and Common Issues

Issue	Handling
Wanting Flocks to replace NDR / TDP for real-time detection	Not recommended. Flocks is for deep analysis after leads are available
Very large alert volume, such as tens of thousands per hour	Slice by time window and alert type
Model hallucination	Require "must list evidence fields; refuse to answer without evidence" in the Skill / Agent prompt
Multi-group push sent to the wrong group	Explicitly specify Session ID
Alert source only has a web page and no API	Use the browser path, see 10.4

---

10.2 Host Forensics

Core question: when facing a Linux host that may be compromised, how can an Agent complete baseline collection → timeline reconstruction without damaging the environment? Unlike alert triage, every command runs on a real machine. Flocks decouples sensitive operations from AI automation through a command allowlist / blocklist plus per-command human confirmation.

Inputs / Outputs

• Input: target host list, established SSH / bastion channel
• Output: baseline report, deep intrusion report with timeline + IOC + mining pool + brute-force source + persistence method, command execution audit trail

Core Safety Mechanism

Type	Behavior
Allowlist	Pure read-only commands such as ps / netstat / read-only cat paths / last / who are executed automatically
Blocklist	Any write / modify / delete command such as rm / sed -i / kill / iptables -A is rejected directly
Uncategorized / Gray Area	Prompts for confirmation: allow once, always allow, or treat as blocklisted? No action = default blocklist

Meaning: analysts do not need to worry about the Agent damaging machines; high-risk actions require human approval; the full process is auditable.

Steps in WebUI

1. Create a session:

   "Inspect host 10.10.x.x. Start with the baseline, and if anything is abnormal, perform deeper analysis"

2. Rex delegates to the host-inspection Agent: the expert Agent takes over with its own system prompt and tool stack
3. First baseline collection: system information / CPU / memory / processes / network / login records / startup items / cron, all allowlisted
4. Find anomaly → deep investigation: the Agent stops, explains what it found, lists sensitive commands it wants to run, and asks for human confirmation one by one
5. Produce a structured report: host profile / anomaly findings / complete timeline / IOC / recommended actions
6. Optional: convert to a scheduled task or link it into alert triage as an evidence chain

Real Case Walkthrough: Mining Host Timeline Reconstruction, About Four Minutes

Time	Agent action
0:10	Confirms this is the host-inspection / emergency-response Agent
0:33	Rex delegates, and the expert Agent logs into the host
0:42	Runs baseline script with no pop-up because commands are allowlisted
1:06	Sensitive command triggers "allow this time only?" confirmation
1:52	Finds mining traces and enters deep investigation
2:21	Writes report to Workspace
2:58	Timeline: 3/25 system startup → 3/27 abnormal login → 3/27 08:00 mining started
3:14	Full intrusion chain: login / download / scheduled task / files / network indicators
3:33	User notes "some keys were added by me" → Agent avoids misclassification

Output Example

Host: 10.10.x.x
Conclusion: confirmed mining compromise
Timeline:
  2026-03-25        System startup
  2026-03-27 05:18  Abnormal login (brute-force source 185.x.x.x)
  2026-03-27 08:04  Downloaded mining program /tmp/xmrig
  2026-03-27 08:05  Created scheduled task /etc/cron.d/update
  2026-03-27 08:07  Established mining pool connection pool.xxx.com:3333
IOC:
  - Mining pool: pool.xxx.com:3333
  - File: /tmp/xmrig (sha256: ...)
  - Scheduled task: /etc/cron.d/update
Recommendations:
  - Isolate host / remove malicious binary / reset SSH key / block brute-force IP at the boundary

Boundaries

Issue	Handling
Letting the Agent clean up mining by itself	Not recommended. Remediation should be confirmed and executed by a human
Too many gray-area pop-ups	Extend the allowlist in an enterprise Skill
Large host count and insufficient SSH capacity	Use Workflow for batch scheduling
Windows hosts	Current path targets Linux; create a separate expert Agent for Windows

---

10.3 Network Security Product Integration

"Connect the device" is the first step for bringing Flocks into an enterprise. Core decision: integration-method priority + one-sentence API integration.

Integration Method Priority

Priority	Method	Best for	Not suitable for
★★★	Official / private API	Long-term stability, scheduled tasks, batch work	Cases where API truly is not enabled
★★☆	Log push / message queue / relay script	Devices that are event sources	Real-time queries
★☆☆	Browser login and page reading	No API, web console only	Long-running main path

Browser automation is the fallback, not the main path.

Does the Intranet Need Internet Access?

Flocks itself does not strictly require public internet access. The model does. Private / intranet models do not require public internet; external cloud models such as OpenAI and Claude do.

Main API Integration Path

Natural-language assisted integration: after you provide API documentation, authentication method, and typical request examples, Rex can help generate tools, verify the integration, and add them to the platform tool system.

1. Create a new session
2. Describe it briefly:

   "Search the web for the VT API documentation, then help me integrate the VT API service. The Key is in the file I just sent"

3. Rex automatically:
   • Pulls documentation with Web Search, or uses the documentation you pasted
   • Generates Python / API tools from the documentation
   • Fills in the Key
   • Automatically starts call verification
   • Debugs failures until successful
4. The tool enters the Tools directory and becomes available platform-wide
5. Optional: record calling conventions in a Skill, such as rate limits and field mapping

Real Case Walkthrough: VT API Integration From Scratch, About Two Minutes

Time	Rex action
0:02	Assumes device API documentation exists and deletes the existing VT tool first
0:38	One sentence: "search the web for the VT API documentation, then help me integrate it"
1:05	Rex starts Web Search
1:33	Tool creation is complete, but "having a tool" does not mean "it can run"
1:48	Rex continues verifying whether the Key can call normally
2:03	Verification passes and the tool is saved

Value

• Integration speed: work that used to need 2-3 days of development now takes 2-3 minutes
• Reusable: tools enter the Tools directory for global reuse
• Self-correcting: failures are debugged automatically
• Iterative: continue modifying directly in the conversation

API Tool vs MCP

• Used only by Flocks → an API tool is enough
• Reused across multiple AI platforms → use MCP

Boundaries

Issue	Handling
Documentation is Word / PPT / scanned image	Convert to text first with pdftotext / OCR, then give it to Rex
Only a few endpoints are needed	Tell Rex "only integrate /v1/ioc and /v1/sample"
Gets 401 after running for a while	Token expired; refresh the Key in Tools
Integrated fields do not match the business	Ask Rex to add a wrapper layer

---

10.4 Browser Automation and Web Login

Core idea: when a system has no API, Rex can open web pages, log in, click, and extract data like an analyst. Browser automation is the fallback, not the first choice.

Best Fit vs Avoid

Best fit	Avoid
Data can only be fetched from web pages, such as a cloud console without API	The device already has a mature API
One-time investigation	Daily scheduled operations
Human logs in once, then the session stays active	Deployment on remote / headless cloud hosts
Discover backend interfaces for later hardening	Large volume, high frequency
	Compliance-sensitive flows that must be fully auditable

Local Installation vs Docker

Deployment	Headed interactive login	Headless background	Recommended for
Local installation	✅	✅	Human login / QR code / verification code
Docker	❌	✅	Pure background use, API fetching
Remote cloud host	❌	✅	Scheduled tasks, batch processing

"Let me log in manually once, then let Flocks continue" → requires local installation.

Steps

1. Create a session:

   "Open https://example-cloud-security-console.com for me. After I log in, go to the 'Alerts' page and fetch all alerts from the last 24 hours"

2. Rex opens the browser → navigates to the URL → stops at the login page and asks you to take over
3. User scans QR code / enters password / passes verification
4. Rex takes over again: finds entry point → applies time filter → paginates / scrolls → extracts structured data
5. Discover backend interface: read XHR / Fetch, identify the data source, and harden it into a stable API tool

Practical Decision Order

Ask these questions in order when a requirement arrives:

1. Is there an API? If yes → use 10.3
2. Is there log push / MQ / periodic export? If yes → fetch from the aggregation layer
3. Can you request API documentation? If yes → discuss API first
4. If none of the above works → use browser automation

When to Upgrade to an API Tool

When a browser task becomes scheduled, runs stably, and has clear backend interfaces, ask Rex:

"Extract the backend interfaces actually called by this browser flow and generate an independent API tool, so we no longer use the browser next time"

Browser automation should be the bridge in, not the destination.

Boundaries

Issue	Handling
How can someone log in for Docker deployment?	Switch to local deployment, or log in locally and export cookies into Docker
Stuck on the login page	Usually caused by verification code / risk control; hand it to a human
Page revision breaks the flow	Update selectors in the Skill, or let Rex explore again
Strict anti-scraping	Slow down / use API / give up

---

10.5 Threat Intelligence and IOC Triage

Core question: with only one IP / domain / hash, how can an Agent give a cross-validated conclusion within minutes? Flocks lets Rex call multiple intelligence sources at once, including ThreatBook, VT, GreyNoise, and FOFA, then compare them and make a unified judgment with enterprise context.

Inputs / Outputs

• Input: single IOC such as IP / domain / URL / hash, IOC list, related context such as alert / asset
• Output: triage conclusion, such as benign / suspicious / malicious + confidence, tags / family, cross-validation result, recommended action, continuous tracking task

Steps

1. Create a session:

   "Triage IOC 8.8.8.8, query ThreatBook, VT, and GreyNoise, then give a conclusion after cross-checking"

2. Rex identifies the IOC type → calls integrated intelligence tools in parallel → aligns fields
3. Cross-judgment + structured output:
   • When sources conflict, decide based on priorities configured in the Skill
   • Include IOC characteristics, such as 8.8.8.8 being Google Public DNS
   • Provide a one-sentence conclusion + detailed reasoning + recommendation
4. Optional: batch triage / continuous tracking, converted to Task Center

Real Case Walkthrough: 8.8.8.8

Stage	Conclusion
Identification	Public IPv4
Parallel query	ThreatBook / VT / GreyNoise
Field alignment	ThreatBook: Google Public DNS; VT: clean; GreyNoise: scanner hit but tagged benign
Cross-judgment	Multiple sources point to "Google Public DNS, benign infrastructure"; high confidence
Enterprise context	Check recent alerts; if present, indicate "legitimate DNS egress misclassified"
Conclusion	Benign / no remediation required; recommend optimizing the detection-rule allowlist

Output Example

{
  "ioc": "8.8.8.8",
  "type": "ipv4",
  "verdict": "benign",
  "confidence": 0.95,
  "conclusion": "Google Public DNS infrastructure; benign.",
  "sources": {
    "threatbook": {"tags": ["public_dns", "google"], "verdict": "benign"},
    "virustotal": {"malicious": 0, "suspicious": 0},
    "greynoise": {"classification": "benign", "actor": "Google Public DNS"}
  },
  "enterprise_context": {
    "recent_alerts": 42,
    "note": "High alert volume, but all are DNS egress; recommend optimizing the rule allowlist"
  },
  "suggested_action": "allowlist_in_detection_rules"
}

Batch / Continuous Tracking

• Batch: 10 / 50 / 100 IOCs at a time. Rex automatically shards, writes separate artifacts, and produces a summary table
• Continuous tracking: check tag changes / new samples in IOC families / incident TTP updates daily through Task Center

Linkage With Other Scenarios

Downstream	Usage
Alert triage	External IPs / download domains in alerts trigger an IOC triage subprocess
Asset discovery	Check maliciousness of external scanning source IPs
Threat hunting Workflow	Start from IOCs and expand to related samples / C2

Boundaries

Issue	Handling
Conflicting source conclusions	Define priority and aggregation rules in a Skill
Rate limits	Skill-level throttling + cache layer
Only one source integrated	Usable, but confidence is lower; at least two sources are recommended
APT attribution	Treat as reference only, not a final determination

---

10.6 Internet Asset Discovery / ASM

Core question: given a domain / company name, how do you draw a complete map of internet-exposed assets? Flocks' value: multiple external asset-mapping sources + internal CMDB + threat intelligence assembled in one context.

Inputs / Outputs

• Input: root domain / company name / IP range / mixed seeds
• Output: asset inventory, classification view by business / region / environment, risk view, diff view for continuous tracking

Steps

1. Create a session:

   "Discover the internet-facing assets for threatbook.cn, including subdomains, external ports, and Web services, then output them by category"

2. Parallel multi-source discovery: identify seeds → call tools in parallel → deduplicate and merge, using the union of fields and the strictest verdict
3. Classify and aggregate: by business / environment / technology stack / region; classification rules can be captured as a Skill
4. Internal correlation with CMDB: match registered assets / find shadow assets / attach owners / infer ownership from WHOIS or certificates
5. Risk tagging: threat-intelligence lookup / vulnerability intelligence / certificate status
6. Output report: overview + asset list + risk Top N + change list

Real Case Walkthrough: threatbook.cn

Stage	Action
Seed	threatbook.cn
Discovery	Parallel calls to ThreatBook assets + FOFA + certificate transparency logs
Deduplication and merge	For the same IP across sources, use the union of fields
Classification	Main site / official blog / docs / backend / CDN / third-party
Correlation	Match CMDB; real projects usually match 80-90%
Risk tagging	Certificate status / intelligence hit / exposed management backend → priority
Output	Markdown + JSON
Follow-up	Recommend converting to a "weekly asset diff task" and pushing to WeCom

Output Example: Markdown Summary

# Internet Asset Discovery Report for threatbook.cn

## Overview
- Total assets: 42
- Subdomains: 28
- External IPs: 11
- Web services: 21
- Priority focus: 1 management backend directly exposed to the internet

## Classification View
- Main site / official site: www.threatbook.cn, ...
- Product console: console.threatbook.cn
- Documentation: docs.threatbook.cn
- API: api.threatbook.cn
- CDN: xxx.cdn.*

## Risk List
| Asset | Risk | Recommendation |
| --- | --- | --- |
| xxx.threatbook.cn | Old component has CVE-2024-xxxx | Upgrade or take offline |

Continuous Operation: Asset Diff

• Weekly / daily task: rerun discovery → compare with baseline → push added / disappeared / changed assets
• Change signals such as certificate change / Banner change / port change are important risk signals

Boundaries

Issue	Handling
High noise, including assets that are not ours	Capture ownership rules in a Skill: ownership / certificate subject / DNS SOA
Blind spots in a single platform	Cross-check multiple sources + WHOIS + certificate transparency
Shadow assets have no owner	Add a "no owner" section to the report to drive registration
Very large asset volume, such as tens of thousands	Slice by business / department and use distributed Workflow
Compliance boundary	Flocks does not perform offensive scanning; it only uses public asset-mapping data and authorized data sources

---

11. CLI Command Reference

flocks --help

Command	Purpose
flocks start	Start the backend and WebUI
flocks stop	Stop services
flocks restart	Restart services
flocks status	View runtime status
flocks logs	View logs
flocks update	Upgrade to the latest version
flocks task	Manage Task Center
flocks session	Manage sessions, including export / troubleshooting / batch processing
flocks mcp	Manage MCP services
flocks skills	Manage Skills
flocks export / flocks import	Export / import session data
flocks stats	View usage statistics

Most common combination:

flocks start && flocks status && flocks logs

Upgrade / recovery:

flocks stop && flocks restart

---

12. Configuration Index

Configuration domain	Purpose	When to adjust
provider	Model provider, adapter, model collection	Integrating OpenAI Compatible / local / self-hosted gateway
api_services	Enabled state for external security services	Connecting TDP / ThreatBook / Qingteng, etc.
mcp	MCP service integration	Extending external capabilities through MCP
channels	Message channels	Connecting Feishu / WeCom / Slack / DingTalk / Telegram / WhatsApp / Email Integration
sandbox	Execution isolation	Team / production scenarios
server	Service-layer behavior	CORS, etc.
allowReadPaths	Allowed read paths	Explicitly authorizing extra readable paths
updater	Upgrade source and strategy	Adjusting GitHub / Gitee update sources

For first-time configuration, focus on provider, channels, and api_services.

---

13. Glossary

Term	Meaning
Rex	Flocks' default main Agent, responsible for command, analysis, and scheduling
Agent	An intelligent entity that can independently receive goals and execute tasks, and can delegate to sub-agents
Workflow	A runtime unit that organizes analysis steps, node relationships, and I/O constraints into a reusable process
Skill	A capability package that provides domain knowledge, fixed processes, or integration standards to Agents
MCP	Model Context Protocol, a protocol for unified access to external context / tool capabilities
Workspace	A workspace for saving inputs, outputs, intermediate artifacts, and reports
Provider	Model provider / model adapter entry point
Task	A task unit queued, executed, and status-tracked by the system
Channel	A capability that sends messages to external touchpoints such as Feishu / WeCom / Slack / DingTalk / Telegram / WhatsApp / email
Sandbox	Runtime isolation that limits the execution environment, permission scope, and resource boundaries

---

Appendix: Shortest Path for New Users

1. Install: curl -fsSL https://gitee.com/flocks/flocks/raw/main/install_zh.sh | bash
2. Start: flocks start → flocks status → open http://127.0.0.1:5173
3. Configure: model list → add Provider → add model → test connection → set default model
4. Use: enter conversation management and describe your goal to Rex
5. Advance: capture mature investigations as Workflow / Skill, use Task Center for scheduled runs, and push results to WeCom / DingTalk through channels

---

This manual is an offline quick-reference version. For full details and screenshots, visit the Flocks online documentation. For issues not covered by the documentation, first run flocks logs and check Task Center status, then decide which feedback channel to use.