Blackboard in Action

The Central Nervous System

The blackboard is the shared state layer that connects all P4L4D1N agents. Every piece of information that agents produce, consume, or react to flows through the blackboard. Without it, agents would be isolated analyzers producing independent reports. With it, they form a collaborative system where each agent's work improves every other agent's analysis.

In P4L4D1N, the blackboard is implemented on Redis (Upstash in production). Each pentest gets its own namespaced set of Redis keys, and all blackboard operations use a circuit breaker pattern for resilience. Understanding what lives on the blackboard and how agents interact with it is essential for interpreting pentest results and understanding why multi-agent findings are more valuable than single-agent analysis.

Five Data Channels

The blackboard maintains five distinct data channels, each stored in its own Redis structure under the namespace blackboard:{scanId}:

1. Findings

Redis key: blackboard:{scanId}:findings (Redis List)

Findings are the primary output of the pentest. Each finding is a structured JSON object posted by an agent containing:

• agentRole — Which specialist produced this finding
• title — A concise description of the vulnerability
• severity — critical, high, medium, low, or info
• description — Detailed explanation of the vulnerability and its impact
• source — The Phase 1 tool that provided the initial evidence
• vulnType — The vulnerability classification
• proof — Proof-of-concept exploit or evidence demonstrating the vulnerability
• remediation — How to fix the issue
• affectedUrl — The specific URL or endpoint affected
• retestCommand — A Docker command to verify the fix

Any agent can read all findings on the blackboard. This means the API Agent can see what the Infrastructure Agent found, and the Exploit Chain Agent (Blitz tier) can read every finding from every agent to construct attack chains.

2. Leads

Redis key: blackboard:{scanId}:leads (Redis List)

Leads are cross-agent suggestions. When an agent discovers something outside its specialization, it posts a lead identifying which specialist should investigate and what they should look for.

Each lead contains:

• fromAgent — The agent posting the lead
• toAgent — The specialist that should investigate
• message — What to look for and why

For example, the Infrastructure Agent finding an open Redis instance on port 6379 would post a lead to the API Agent: "Open Redis on 6379 with no authentication. Check if session tokens or cached API responses are accessible." The API Agent picks up this lead on its next loop iteration and investigates.

Leads are the mechanism that enables emergent discoveries — findings that no single agent would have produced alone. The Infrastructure Agent knows Redis is open; the API Agent knows how to check for session token exposure. The lead connects these two pieces of knowledge.

3. Agent Status

Redis key: blackboard:{scanId}:agent:{role}:status (Redis String)

Each agent maintains a status value on the blackboard: running, done, or error. The orchestrator monitors these statuses to track progress and detect when all agents have completed.

The status channel also enables the live agent activity panel in the TurboPentest UI. Users watching a pentest in progress can see which agents are actively working, which have completed, and whether any have encountered errors.

4. Chat

Redis key: blackboard:{scanId}:chat (Redis List)

The chat channel supports bidirectional communication between human operators and agents. Messages are structured JSON objects with a sender (from), message text, an optional target agent (toAgent), and a timestamp.

Human-to-agent messages allow operators to provide real-time guidance during a pentest. A user might post "Focus on the admin panel at /manage" or "Skip TLS findings, we are behind a load balancer." Agents check for user directives on each loop iteration and factor them into their analysis. When an agent acknowledges a directive, it posts a response to the chat channel.

Agent-to-human messages include acknowledgment of directives and status updates. Agents report how many findings they produced in each cycle and confirm that they received user guidance.

The chat channel is advisory, not commanding. Agents consider user directives as context for their analysis, not as overriding instructions. If a user says "skip XSS findings" but the Web Agent discovers a critical stored XSS, the agent will still report it — safety and thoroughness take precedence.

5. Assignments

Redis key: blackboard:{scanId}:assignments (Redis List)

Assignments are instructions from the orchestrator or supervisor to specific agents. They direct agents to focus on particular areas, investigate specific leads, or adjust their analysis strategy.

The assignment channel is primarily used by the supervisor (Standard tier and above) to coordinate agent work. If two agents appear to be investigating the same issue, the supervisor can assign one to a different focus area to maximize coverage.

Circuit Breaker Resilience

All blackboard operations are wrapped in a circuit breaker pattern via withCircuitBreaker(). If Redis becomes temporarily unavailable, agents continue working with their own local state rather than failing. This means:

• A Redis blip does not crash the pentest
• Agents that cannot read the blackboard still produce findings from their Phase 1 analysis
• Agents that cannot post to the blackboard accumulate findings locally
• When Redis recovers, normal blackboard operations resume

This resilience design ensures that infrastructure issues degrade gracefully rather than causing total failure. A pentest with intermittent Redis issues produces fewer cross-agent correlations but still produces validated findings from each agent's independent analysis.

Blackboard Lifecycle

Each pentest's blackboard has a defined lifecycle:

1. Creation — When agents are launched, the blackboard namespace is initialized
2. Active use — Agents read and write throughout the pentest
3. Wrap-up — The orchestrator signals wrap-up via signalWrapUp(), setting a flag that agents check on each loop iteration
4. Synthesis — After all agents complete, the synthesis process reads the entire blackboard to compile the final report
5. Cleanup — cleanupBlackboard() deletes all keys in the namespace, freeing Redis memory

The cleanup step ensures that completed pentests do not consume Redis storage indefinitely. All findings are persisted to the PostgreSQL database during synthesis, so the Redis data is purely ephemeral working state.

Reading the Blackboard as a User

When you view a pentest in the TurboPentest UI, the live agent activity panel is reading the blackboard in real time. You can see:

• Which agents are active, done, or in error state
• How many findings each agent has posted
• Leads being exchanged between agents
• Chat messages between you and the agents

This transparency lets you understand not just what was found, but how it was found — which agent discovered it, which leads contributed to it, and how the collaborative process produced the final result.