Phoenix Protocol is an adaptive, agentic network security compliance auditor. It helps security administrators inspect network-device configuration files, identify security weaknesses, explain why those weaknesses matter, and recommend vendor-specific corrections.
Phoenix Protocol is a web application that turns complex network configurations into clear security findings and practical remediation steps.
Start both the Flask backend and Vite frontend with a single cross-platform command:
python start.pyThis launcher:
- Verifies that Python and Node/npm runtimes and dependencies are installed.
- Automatically detects port conflicts and finds fresh, available ports (default backend:
http://localhost:5001, default frontend:http://localhost:5173) so services never collide with existing applications. - Performs readiness polling on
/healthand frontend root until both services are fully responsive. - Automatically opens the freshly allocated frontend URL in your default browser (pass
--no-browserto disable). - Gracefully stops all child processes and process groups on
Ctrl+Cor shutdown signals.
# Start services with automatic port allocation (opens browser automatically)
python start.py
# Start services without auto-opening the web browser
python start.py --no-browser
# Run on custom preferred ports
python start.py --port-backend 5001 --port-frontend 5174
# Exit with an error if requested ports are busy instead of auto-reallocating
python start.py --strict-portsA user uploads a configuration from a network device. Phoenix Protocol identifies the device vendor and platform, interprets the configuration, converts it into a common security format, and evaluates it against selected compliance rules.
The system then presents the results in a dashboard. Each finding includes the relevant configuration evidence, the failed security requirement, its severity, the user's compliance score, and a suggested correction.
The system is designed to support configurations from multiple vendors, including Cisco, Juniper, Fortinet, and Palo Alto. It can also handle unfamiliar configuration commands through its adaptive Teach the Auditor feature.
Configuration upload
↓
Vendor and platform discovery
↓
Configuration normalization
↓
Compliance evaluation
↓
Risk and severity analysis
↓
Vendor-specific remediation
↓
Human review and approval
↓
Compliance report
| Feature | Description |
|---|---|
| Configuration upload | Accepts network configuration files and, where supported, configuration exports or screenshots. |
| Vendor discovery | Identifies the likely vendor, operating system, device type, and version. |
| Normalization | Converts different vendor syntaxes into a shared security configuration schema. |
| Compliance analysis | Checks the normalized configuration against a curated set of CIS, NIST, STIG, or similar rules. |
| Evidence-based findings | Shows the exact configuration line or property that caused a finding. |
| Risk scoring | Classifies issues as Critical, High, Medium, or Low and calculates an overall score. |
| Remediation guidance | Suggests a vendor-specific command or configuration change. |
| Teach the Auditor | Lets an administrator define the meaning of an unfamiliar command and save the mapping for future audits. |
| Human approval | Prevents potentially risky remediation actions from being executed automatically. |
| Reporting | Produces a readable compliance report, including findings, evidence, scores, and recommendations. |
The main differentiator is that Phoenix Protocol is not limited to a fixed list of known configuration formats. When it encounters an unfamiliar command, it can ask an administrator to explain the command's security meaning. The system stores that explanation as a reusable configuration mapping.
This means Phoenix Protocol learns configuration mappings, not model weights. The feature should therefore be described as an adaptive configuration knowledge base, rather than as AI model retraining.
Phoenix Protocol uses artificial intelligence where interpretation is useful and deterministic rules where security decisions must be reliable.
| Responsibility | Responsible component |
|---|---|
| Understand what a configuration command means | AI agents |
| Convert vendor syntax into a common schema | Normalization agent and validated schemas |
| Decide whether a security requirement passes or fails | Curated deterministic compliance rules |
| Explain findings and estimate interpretation confidence | AI agents and audit metadata |
| Suggest how to correct a finding | Remediation agent with human review |
The guiding principle is:
AI decides what the configuration means. Rules decide whether it is compliant. AI suggests how to remediate it.
The project can use Google Agent Development Kit (ADK) to coordinate specialized agents:
- Root Agent: Coordinates the complete audit process.
- Discovery Agent: Identifies the vendor, platform, model, version, and configuration format.
- Normalization Agent: Translates vendor-specific syntax into a common security schema.
- Compliance Agents: Evaluate the normalized configuration against selected frameworks. Independent framework checks can run in parallel.
- Risk Agent: Combines findings into severity levels and an overall compliance score.
- Remediation Agent: Generates vendor-specific correction guidance.
A simplified execution sequence is:
Root Agent
├── Discovery Agent
├── Normalization Agent
├── CIS / NIST / STIG checks in parallel
├── Risk Agent
└── Remediation Agent
Phoenix Protocol is an adaptive web-based network security compliance auditor that uses AI agents to understand multi-vendor configurations, deterministic rules to evaluate security, and human-approved remediation to help organizations secure their network infrastructure.
Click to expand and view application screenshots
The repository is organized into dedicated top-level workspaces:
phoenix-protocol/
│
├── frontend/ # React/Vite single-page application & dashboard UI
│ ├── src/ # Components, pages, motion effects, and styling
│ ├── public/ # Static assets and branding
│ └── package.json
│
├── backend/ # Flask REST API, scanner engine, AI agents, and knowledge base
│ ├── app/ # Authoritative backend application package
│ │ ├── api/ # Flask REST API routes (/health, /scan)
│ │ ├── services/ # Scanner and compliance service
│ │ ├── parsers/ # Network configuration parsers
│ │ ├── rules/ # NET-001..NET-010 deterministic rules
│ │ └── agents/ # Teach-the-Auditor & remediation agents
│ ├── knowledge/ # Persistent Teach-the-Auditor knowledge layer
│ ├── examples/ # Executable end-to-end integration demo
│ ├── sample_data/ # Network configuration test fixtures
│ ├── tests/ # Automated test suite (177 tests)
│ └── requirements.txt # Python runtime and test dependencies
│
├── docs/ # Documentation, audit reports, screenshots, and visual branding
│ ├── audit/ # 15 thematic audit reports & black-box evidence
│ ├── screenshots/ # Application interface captures
│ ├── logo/ # High-resolution logos & vector graphics
│ └── script.md # Presentation script & teacher walkthrough
│
└── .github/ # Repository community standards, issue templates & governance
For full backend documentation, architecture details, and endpoint contracts, see backend/README.md.
cd backend
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
# Run the Flask API server (port 5000)
flask --app "app.api:create_app()" run --port 5000
# Run full backend test suite
python -m pytest -vFor frontend details, see frontend/README.md.
cd frontend
npm install
npm run devReturns service operational health metadata.
Response (200 OK):
{
"status": "healthy",
"service": "phoenix-protocol",
"version": "1.0.0"
}Uploads one or more network device configuration files and triggers deterministic compliance analysis.
- Content-Type:
multipart/form-data - Parameters:
fileorfiles: One or more configuration files (up to 10 MB each).device_type(optional): Requested device profile. Currently supported:cisco_ios(default).
Response (201 Created):
{
"scan_id": "scan_b2c47a59e...",
"status": "completed",
"device_type": "cisco_ios",
"parser_version": "1.0.0",
"rule_set_version": "1.0.0",
"summary": {
"total_rules": 10,
"passed_rules": 10,
"failed_rules": 0,
"warning_rules": 0,
"not_applicable_rules": 0,
"error_rules": 0,
"tested_rule_compliance": 100.0
},
"compliance_score": 100.0,
"devices": [
{
"device_id": "9b1deb4d...",
"name": "CORE-RTR-01",
"display_name": "CORE-RTR-01",
"vendor": "Cisco",
"device_type": "cisco_ios",
"source_filename": "core_rtr.cfg",
"parse_status": "success",
"line_count": 85,
"error_message": null,
"summary": {
"total_rules": 10,
"passed_rules": 10,
"failed_rules": 0,
"warning_rules": 0,
"not_applicable_rules": 0,
"error_rules": 0,
"tested_rule_compliance": 100.0
},
"compliance_score": 100.0,
"results": [
{
"rule_id": "NET-001",
"status": "pass",
"severity": "high",
"evidence": "transport input ssh",
"evidence_line_range": "45-46",
"message": "Telnet is disabled on all administrative VTY line blocks (SSH-only enforced).",
"remediation": "line vty 0 4\n transport input ssh"
}
]
}
]
}Retrieves a previously evaluated scan by its unique scan ID directly from SQLite persistence.
- Response (200 OK): Standardized Phoenix Protocol scan result matching the contract above.
- Response (404 Not Found):
{"error": "Scan not found", "detail": "...", "scan_id": "..."}
Teach-the-Auditor is Phoenix Protocol's adaptive intelligence component powered by the Google Agent Development Kit (ADK). When an unfamiliar network configuration command is encountered during parsing or auditing, Teach-the-Auditor interprets its security semantics without replacing deterministic compliance evaluation.
UnknownCommand
↓
TeachAuditorService
↓
KnowledgeProvider (Tool: lookup_known_command)
├── [FOUND] → Trusted interpretation (requires_human_approval = False)
└── [NOT FOUND] → Google ADK Agent (output_schema: CommandInterpretation)
↓
TeachingProposal (requires_human_approval = True)
↓
(Human Review & Dev2 KnowledgeService Persistence)
The core trust boundary is strictly enforced:
- AI understands syntax and explains security meaning.
- Deterministic rules evaluate whether a configuration passes or fails.
- High-consequence actions (learning/persistence) require human approval.
- Under no circumstances does the agent produce
pass/failcompliance verdicts.
Defined in app/agents/schemas.py:
class UnknownCommand(BaseModel):
vendor: str # e.g., 'Cisco', 'Arista', 'Juniper'
platform: str # e.g., 'IOS', 'EOS', 'JunOS'
command: str # Raw or normalized command string
context: Optional[Union[str, List[str]]] = None # Surrounding config block
source_line: Optional[int] = None # 1-based source line numberStructured output produced by the ADK agent and validated with Pydantic:
class CommandInterpretation(BaseModel):
command: str # Target command string
vendor: str # Target vendor
platform: str # Target platform
meaning: str # Concise operational explanation
security_control: str # Control area (e.g. transport_security, logging)
mapped_rule_id: Optional[str] = None # Optional NET-001..NET-010 or null
confidence: float # Strictly bounded: 0.0 <= confidence <= 1.0
explanation: str # Semantic rationale justifying mappingmapped_rule_idis strictly optional (Noneis permitted). The LLM is never forced to invent rule IDs.- Invented or hallucinated rule IDs outside the curated catalog (
NET-001throughNET-010) are rejected at the schema validation boundary.
Abstract interface decoupling Teach-the-Auditor from any specific database implementation:
class KnowledgeProvider(ABC):
@abstractmethod
def lookup_command(
self, vendor: str, platform: str, command: str
) -> Optional[CommandInterpretation]:
"""Look up an existing verified interpretation for a command."""
raise NotImplementedErrorMockKnowledgeProvider: In-memory, case- and whitespace-insensitive reference implementation used for deterministic unit testing and offline development.- The agent accesses this abstraction through a single dedicated tool:
lookup_known_command().
AI-generated interpretations are packaged into a proposal enforcing human review:
class TeachingProposal(BaseModel):
interpretation: CommandInterpretation
requires_human_approval: bool = True # Always True for new AI interpretations
source: str = "ai_agent" # 'knowledge_base' or 'ai_agent'- Newly generated AI interpretations are never silently committed or persisted.
- Pre-existing mappings loaded from the
KnowledgeProvidersetrequires_human_approval = Falseas they have already undergone prior verification.
In Phoenix Protocol:
- Determinism: Regulatory compliance (e.g., CIS, NIST, PCI-DSS) requires mathematically reproducible audits. Two scans of identical configurations must yield identical scores.
- Audit Defensibility: Security findings must cite verifiable evidence and deterministic rule logic rather than probabilistic LLM outputs.
- Role Separation: AI interprets ambiguous syntax (e.g., unfamiliar vendor commands); deterministic rules evaluate compliance against security thresholds; humans authorize policy additions.
Dev2 is independently developing the persistent KnowledgeService in her branch/component. Once complete, integration requires zero changes to the ADK agent or schemas:
- Dev2's service will provide persistent storage (e.g., SQLite/PostgreSQL) with
lookup_command(),propose_mapping(),approve_mapping(), andreject_mapping(). - An adapter implementing
KnowledgeProviderwill wrap herKnowledgeService.lookup_command(). - When
TeachingProposalis approved by a human administrator, the proposal will be forwarded to herapprove_mapping()method for long-term persistence.
Phoenix Protocol is an open-source project stewarded by The Coastal Assassins. We welcome contributions and community involvement!
- Maintainers: Meet the core team members guiding the project.
- Contributing: Check out our contribution guidelines, development setup, and PR process.
- Code of Conduct: We are committed to fostering a welcoming and inclusive environment.
- Security: Read our security policy and how to report vulnerabilities.
- License: Phoenix Protocol is released under the MIT License.