docs(architecture): baseline current design (#109)
Capture the brownfield architecture and its relationship to the project vision.\n\n- add the current-state SAD and five retrospective ADRs\n- classify vision vectors against implementation evidence\n- record requirements, risks, gates, and construction handoff
This commit is contained in:
1 parent
937c6e9837
commit
b192577b54
28 files changed
+1076
No files matched your search
@@ -0,0 +1,80 @@
|
||||
# Codebase Analysis Report
|
||||
|
||||
**Project:** T3MP3ST
|
||||
**Directory:** `/home/roctinam/dev/bt6/T3MP3ST`
|
||||
**Generated:** 2026-07-20
|
||||
**Revision:** `186afe6b50e365371774aa2ed7986d73eb0656db`
|
||||
|
||||
## Summary
|
||||
|
||||
- **Tracked files:** 1,665
|
||||
- **Primary implementation:** TypeScript/Node.js ESM
|
||||
- **Source size:** 111 TypeScript files and approximately 46,129 lines under `src/`
|
||||
- **Test indicators:** 75 test/spec-named files in `src/` and `scripts/`
|
||||
- **Documentation:** 52 Markdown files in `docs/` and `docsite/`
|
||||
- **Architecture:** Modular monolith with CLI, localhost web/API, MCP, model/provider, agent orchestration, tool adapters, evidence/reporting, and benchmark subsystems
|
||||
- **Profile:** Established open-source security product with stable core and explicitly experimental/research modules
|
||||
- **Team signal:** More than ten author identities and 151 commits in the last year; exact active human team size is unknown
|
||||
|
||||
## Evidence-Based Inferences
|
||||
|
||||
### High Confidence
|
||||
|
||||
- T3MP3ST is an authorized-use offensive-security platform (`README.md`, `SECURITY.md`).
|
||||
- The runtime is Node.js/TypeScript and package version is 1.0.0 (`package.json`).
|
||||
- Users can operate through CLI, browser War Room/API, and MCP (`package.json`, `src/`, developer docs).
|
||||
- The server and Docker deployment bind to loopback by default (`docs/DEVELOPER_GUIDE.md`, `docker-compose.yml`).
|
||||
- The architecture is a modular monolith rather than microservices (`src/` layout, one application image/service).
|
||||
- CI has extensive quality, provenance, claim, safety, and smoke gates (`.github/workflows/ci.yml`).
|
||||
- The repository uses committed benchmark corpora and deterministic claim verification (`bench/`, README, scripts).
|
||||
- Real offensive tools and sensitive artifacts make scope, approval, credentials, and evidence primary risk domains (`SECURITY.md`, `src/arsenal/`, Docker mounts).
|
||||
|
||||
### Medium Confidence
|
||||
|
||||
- The contributor community is medium-to-large for an open-source project, but aliases and automated-agent identities prevent an exact human team count.
|
||||
- The system is production-grade as a distributed open-source tool, while not necessarily operated as a production hosted service.
|
||||
- Reliability maturity is moderate: strong pre-release verification exists, but no hosted-service SLO/telemetry model is evident.
|
||||
- Security maturity is strong for the product category, but certification and organization-level controls cannot be inferred.
|
||||
|
||||
### Unknown
|
||||
|
||||
- Active users, installations, and workload volume
|
||||
- Maintainer staffing, funding, and availability
|
||||
- General support/on-call model
|
||||
- Formal contractual or regulatory obligations
|
||||
- Production incident rate and recovery objectives
|
||||
- Near-term product priority and deadline
|
||||
- Whether package repository metadata intentionally remains pointed at the upstream owner
|
||||
|
||||
## Quality Assessment
|
||||
|
||||
### Strengths
|
||||
|
||||
- Clear stable/experimental/roadmap labeling
|
||||
- Strong verification culture and reproducible public claims
|
||||
- Extensive automated CI gates
|
||||
- Broad documentation for operators, developers, security, benchmarks, releases, and integrations
|
||||
- Localhost-first deployment and explicit authorization doctrine
|
||||
- Modular source organization and multiple integration surfaces
|
||||
- Private vulnerability-reporting process and response target
|
||||
|
||||
### Risks and Weaknesses
|
||||
|
||||
- Large capability surface and external-tool ecosystem amplify regression and supply-chain risk.
|
||||
- Stable and experimental code share core execution and brand surfaces.
|
||||
- Multi-agent/swarm reliability is less demonstrated than single-agent benchmark performance.
|
||||
- No formal workload/capacity baseline was found.
|
||||
- Sensitive artifacts rely heavily on operator-controlled local storage.
|
||||
- Repository ownership references differ between current tracker configuration and `package.json`.
|
||||
- Eighteen debt markers in implementation/script paths need owner triage.
|
||||
|
||||
## Generated Files
|
||||
|
||||
- `.aiwg/intake/project-intake.md`
|
||||
- `.aiwg/intake/solution-profile.md`
|
||||
- `.aiwg/intake/option-matrix.md`
|
||||
- `.aiwg/intake/codebase-analysis-report.md`
|
||||
|
||||
## Recommended Next Action
|
||||
|
||||
Have maintainers validate the five owner questions in `option-matrix.md`, then select incremental expansion, stabilization, research, or hosted evolution as the governing near-term path. The code evidence favors incremental expansion with explicit safety and benchmark promotion gates.
|
||||
@@ -0,0 +1,44 @@
|
||||
# SDLC Accelerate Intake — T3MP3ST
|
||||
|
||||
**Entry mode:** Existing codebase
|
||||
**Baseline revision:** `186afe6b50e365371774aa2ed7986d73eb0656db`
|
||||
**Guidance:** Capture architecture and design as current state, emphasize SAD/ADRs, and test alignment between `VISION.md` and implemented code.
|
||||
|
||||
## Problem Statement
|
||||
|
||||
Offensive-security capability is costly to assemble, difficult to coordinate, and easy to overstate. T3MP3ST provides a local-first orchestration platform that connects an operator's existing coding agent or model provider to scoped reconnaissance, exploitation, evidence, verification, and reporting workflows while retaining authorization and provenance controls.
|
||||
|
||||
## Stakeholders
|
||||
|
||||
- Authorized security operators and researchers
|
||||
- Project maintainers and contributors
|
||||
- Developers integrating through CLI, HTTP, library, or MCP surfaces
|
||||
- Target/system owners who authorize engagements
|
||||
- Recipients of verified findings and coordinated disclosures
|
||||
|
||||
## Current-State Scope
|
||||
|
||||
The implemented system is a TypeScript modular monolith with CLI, localhost War Room/API, MCP server, mission/admiral/operator orchestration, target and OPSEC controls, arsenal adapters, evidence/reporting, provider abstraction, source ingestion, and reproducible benchmarks. Stable, experimental, research, and planned capabilities remain explicitly distinct.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
1. Every stable public capability claim remains re-derivable through `npm run verify-claims` and CI.
|
||||
2. Networked operations reject out-of-scope public targets by default and require explicit authorization context.
|
||||
3. The current-state SAD traces every core use case and names concrete implementation modules.
|
||||
4. Major implemented design choices have accepted retrospective ADRs with evidence and consequences.
|
||||
5. Every vision vector is classified as implemented, partial/experimental, research, or future without presenting aspiration as current state.
|
||||
|
||||
## Constraints
|
||||
|
||||
- Node.js 18+ and TypeScript/ESM
|
||||
- Local-first and self-hosted operation, including connected local agents
|
||||
- Real offensive tooling only for authorized targets
|
||||
- Sensitive credentials/evidence remain operator-controlled
|
||||
- AGPL-3.0-or-later licensing
|
||||
- Existing CLI, HTTP, MCP, and benchmark interfaces require compatibility discipline
|
||||
|
||||
## Out of Scope for This Baseline
|
||||
|
||||
- Redesigning or implementing roadmap features
|
||||
- Claiming hosted-service scale, enterprise certification, or production SLOs without evidence
|
||||
- Treating `VISION.md` as an implemented specification
|
||||
@@ -0,0 +1,134 @@
|
||||
# Option Matrix (Project Context and Intent)
|
||||
|
||||
**Purpose:** Capture what the project is and expose the decisions that owner input must complete.
|
||||
**Generated:** 2026-07-20
|
||||
|
||||
## Project Reality
|
||||
|
||||
T3MP3ST is a mature, self-hosted TypeScript offensive-security platform with a local browser UI, CLI, HTTP API, MCP integration, external security-tool adapters, reproducible benchmarks, and extensive documentation. Its stable core operates real tools against authorized targets, while selected multi-agent, domain-specific, and evolutionary capabilities remain experimental or planned.
|
||||
|
||||
### Audience and Scale
|
||||
|
||||
| Attribute | Current evidence | Confidence |
|
||||
| --- | --- | --- |
|
||||
| Audience | Authorized operators, researchers, CTF users, developers, contributors | High |
|
||||
| Distribution | Open-source package/repository, self-hosted execution | High |
|
||||
| Active users/installations | Not measurable from the codebase | Unknown |
|
||||
| Support expectations | Documentation and security-response target exist; no general SLA found | Medium |
|
||||
| Geographic reach | Public open-source distribution implies global reach | Medium |
|
||||
| Runtime concurrency | Local missions and agent/tool tasks; fleet scale unknown | Medium |
|
||||
|
||||
### Deployment and Infrastructure
|
||||
|
||||
| Attribute | Current state |
|
||||
| --- | --- |
|
||||
| Deployment model | Hybrid local application: CLI + browser UI/API + MCP + external tools |
|
||||
| Hosting | Developer/operator workstation or Docker host; HTTP binds to loopback by default |
|
||||
| Persistence | Local config, browser localStorage, reports, evidence, benchmark artifacts |
|
||||
| Application database | None detected |
|
||||
| CI/CD | GitHub Actions quality pipeline; no hosted-production deployment pipeline detected |
|
||||
| Complexity | Modular monolith with many external integrations and high-risk execution boundaries |
|
||||
|
||||
### Technical Complexity
|
||||
|
||||
- Approximately 46,129 lines across 111 TypeScript files under `src/`
|
||||
- 1,665 tracked files, dominated by committed JSON benchmark artifacts
|
||||
- TypeScript primary; supporting JavaScript/MJS, shell, YAML, Python, C, Java, Go, Rust, Perl, HTML, and container definitions
|
||||
- 75 test/spec-named files in `src/` and `scripts/`
|
||||
- 52 Markdown documentation files across `docs/` and `docsite/`
|
||||
- High-risk factors: real offensive operations, credentials, external tools, network access, sensitive evidence, model nondeterminism, multi-provider compatibility, and public benchmark claims
|
||||
|
||||
## Constraints and Context
|
||||
|
||||
### Known
|
||||
|
||||
- AGPL-3.0-or-later open-source licensing
|
||||
- Node.js 18+ runtime and Node.js 22 CI
|
||||
- Local-first/keyless operation is a core product promise
|
||||
- Authorized use and target scope are non-negotiable safety constraints
|
||||
- Claims are expected to be reproducible from committed evidence
|
||||
- Stable versus experimental status must remain explicit
|
||||
- The project supports a heterogeneous contributor base and multiple provider/runtime environments
|
||||
|
||||
### Unknown
|
||||
|
||||
- Maintainer availability and budget
|
||||
- User/install base and growth targets
|
||||
- Revenue or funding model
|
||||
- Contractual obligations and general support SLA
|
||||
- Formal compliance or certification objectives
|
||||
- Release cadence and next milestone
|
||||
- Current highest-priority pain point
|
||||
|
||||
## Priorities and Trade-offs
|
||||
|
||||
The codebase supports this provisional weighting, which must be validated by owners:
|
||||
|
||||
| Criterion | Provisional weight | Evidence-based rationale |
|
||||
| --- | ---: | --- |
|
||||
| Quality and security | 0.35 | Real offensive actions, secrets, evidence, authorization, and reputation risk |
|
||||
| Reliability and scale | 0.25 | Mission orchestration and tool/model execution must fail safely; actual fleet scale is unknown |
|
||||
| Delivery speed | 0.25 | Active roadmap and competitive research space favor iteration |
|
||||
| Cost efficiency | 0.15 | Local/keyless operation is a product value, but maintainer budget is unknown |
|
||||
| **Total** | **1.00** | Provisional only |
|
||||
|
||||
**Optimizing for:** Credible, reproducible offensive-security capability that remains safe-by-default and accessible through infrastructure users already possess.
|
||||
|
||||
**Likely acceptable trade-off:** Experimental capabilities may iterate before they are fully reliable if maturity is conspicuous and shared safety boundaries remain enforced.
|
||||
|
||||
**Non-negotiable:** Authorization, target containment, secret protection, evidence integrity, honest capability claims, and human control over disclosure or materially dangerous actions.
|
||||
|
||||
## Decision Options
|
||||
|
||||
| Option | Description | Benefits | Risks | Best fit |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| A. Stabilize the core | Concentrate on existing stable paths, safety boundaries, docs, and release quality | Highest trust and lower regression surface | Slower domain expansion | Reliability or adoption is the immediate goal |
|
||||
| B. Incremental expansion | Promote one experimental domain at a time using explicit benchmark and safety gates | Balanced learning and credibility | Requires disciplined promotion criteria | Default recommendation from code evidence |
|
||||
| C. Swarm-first research | Prioritize multi-agent coordination and evolutionary capability | Differentiated research upside | Cost, nondeterminism, and safety complexity | Research funding and tolerance are explicit |
|
||||
| D. Hosted/enterprise evolution | Add centralized service operations, tenancy, governance, and compliance | Broader organizational adoption | Major architecture and operating-model change | Real customer demand and resources exist |
|
||||
|
||||
## Framework Application
|
||||
|
||||
**Recommended now:**
|
||||
|
||||
- Full rigor for core safety, release, provenance, and claim-bearing paths
|
||||
- Moderate rigor for experimental modules
|
||||
- Architecture decisions for trust boundaries and maturity promotion
|
||||
- Continuous security, architecture, risk, and test-strategy cycles
|
||||
- Operational runbooks for local server, agent/provider failures, external tools, and sensitive artifacts
|
||||
|
||||
**Defer unless triggered:**
|
||||
|
||||
- Enterprise governance and formal change boards
|
||||
- Hosted multi-tenant architecture
|
||||
- Multi-region infrastructure and centralized observability
|
||||
- Formal compliance certification work
|
||||
|
||||
**Adaptation triggers:**
|
||||
|
||||
- Hosted service or centrally retained user/target data
|
||||
- Contractual SLA or regulated customer requirement
|
||||
- Material growth in maintainers or release frequency
|
||||
- Dangerous-tool surface expansion
|
||||
- Experimental capability promoted to stable
|
||||
- Public claims not fully covered by deterministic verification
|
||||
- Significant user/install growth or recurring production incidents
|
||||
|
||||
## Owner Validation Needed
|
||||
|
||||
To finalize intent rather than infer it from code, owners should answer:
|
||||
|
||||
1. What decision or milestone triggered this intake?
|
||||
Transition to AIWG memory system
|
||||
|
||||
2. Which matters most for the next release: stability, domain expansion, swarm research, or adoption?
|
||||
all of the above
|
||||
|
||||
3. What is the current user/install scale and expected 12-month change?
|
||||
thousands to tens of thousands
|
||||
|
||||
4. What failures would be unacceptable beyond the documented authorization constraints?
|
||||
none, failsafe patterns always
|
||||
|
||||
5. Are there contractual, funding, compliance, or support commitments not represented in the repository?
|
||||
no
|
||||
@@ -0,0 +1,170 @@
|
||||
# Project Intake Form (Existing System)
|
||||
|
||||
**Document type:** Brownfield system documentation
|
||||
**Generated:** 2026-07-20
|
||||
**Source:** Codebase analysis of `/home/roctinam/dev/bt6/T3MP3ST`
|
||||
|
||||
## Metadata
|
||||
|
||||
- **Project:** T3MP3ST — Tactical Execution Multi-agent Platform for Elite Security Testing
|
||||
- **Repository:** `https://github.com/jmagly/T3MP3ST.git` (`origin`); package metadata references `elder-plinius/T3MP3ST`
|
||||
- **Version:** 1.0.0 in `package.json`; analyzed revision `186afe6`
|
||||
- **License:** AGPL-3.0-or-later
|
||||
- **Runtime:** Node.js 18+; CI uses Node.js 22
|
||||
- **Last analyzed commit:** 2026-07-20, “add reproducible cross-model benchmark matrix”
|
||||
- **Stakeholders:** Maintainers, contributors, authorized security operators, security researchers, and users of supported coding agents
|
||||
|
||||
## System Overview
|
||||
|
||||
T3MP3ST is a self-hosted, multi-agent offensive-security framework for authorized testing, research, and education. It coordinates reconnaissance, exploitation, evidence, and reporting through a CLI, a browser War Room, an HTTP API, and an MCP server. It supports hosted LLM providers, connected local coding-agent CLIs, and local OpenAI-compatible inference servers.
|
||||
|
||||
**Current status:** Established open-source product with stable core paths, experimental subsystems, and research/roadmap modules explicitly distinguished in project documentation.
|
||||
|
||||
**Known audiences:**
|
||||
|
||||
- Authorized penetration testers and red-team operators
|
||||
- Security researchers and CTF users
|
||||
- Developers integrating security workflows through HTTP or MCP
|
||||
- Contributors extending operators, tools, benchmarks, and target adapters
|
||||
|
||||
Actual installation count, active-user count, commercial use, support commitments, and production fleet size are **unknown**.
|
||||
|
||||
## Current Scope and Features
|
||||
|
||||
Evidence in `README.md`, `FEATURES.md`, `src/`, and `bench/` shows these major capabilities:
|
||||
|
||||
- Multi-agent mission planning and execution with an Op Admiral coordinator
|
||||
- Eight operator archetypes covering the offensive-security kill chain
|
||||
- Target definition, rules of engagement, and egress-scope containment
|
||||
- Tool-backed reconnaissance and exploitation adapters
|
||||
- Evidence collection, findings, reports, verification, and disclosure drafting
|
||||
- CLI and localhost-only browser War Room
|
||||
- Express HTTP API and stdio MCP server
|
||||
- Provider/model abstraction for cloud, local, and connected coding-agent execution
|
||||
- White-box source ingestion for multiple programming languages
|
||||
- Benchmark and claim-verification suites for XBEN, Cybench, CVE hunting, cloud, mobile, binary, and evolutionary experiments
|
||||
- Docker-based runtime and isolated CTF challenge environments
|
||||
|
||||
The repository honestly marks cloud, mobile, binary/reverse-engineering, swarm reliability, and some advanced modules as scaffolding, experimental, or research rather than uniformly production-ready.
|
||||
|
||||
## Architecture
|
||||
|
||||
**Style:** Modular monolith with multiple delivery surfaces and externally executed tools.
|
||||
|
||||
**Primary components:**
|
||||
|
||||
- `src/cli.ts` and `src/index.ts`: command-line and library entry points
|
||||
- `src/server.ts`: Express API and static War Room host
|
||||
- `src/mcp-server.ts`: MCP stdio integration
|
||||
- `src/orchestration/`, `src/mission/`, `src/admiral/`, `src/operators/`: planning, coordination, and mission lifecycle
|
||||
- `src/arsenal/`: tool catalog, adapters, parsers, approvals, and post-exploitation support
|
||||
- `src/target/`, `src/opsec/`, `src/evidence/`, `src/reporting/`: scope, safety, evidence, and deliverables
|
||||
- `src/llm/`, `src/config/`: provider/model and runtime configuration
|
||||
- `src/recon/`: black-box and multi-language white-box reconnaissance
|
||||
- `bench/`: reproducible evaluation data and benchmark harnesses
|
||||
- `ctf/`: isolated challenge manifests, executor, and containers
|
||||
- `docs/` and `docsite/`: operator, developer, architecture, and release documentation
|
||||
|
||||
**Persistence:** Primarily local configuration and filesystem artifacts. Docker mounts `reports/` and `evidence/`. Browser settings use localStorage. No application database is evident.
|
||||
|
||||
**Integration points:**
|
||||
|
||||
- Hosted model APIs and local OpenAI-compatible inference endpoints
|
||||
- Connected local coding-agent CLIs
|
||||
- MCP-aware clients
|
||||
- Security command-line tools and network services
|
||||
- GitHub for source, collaboration, releases, and private security advisories
|
||||
- Pagenary for documentation publishing
|
||||
|
||||
## Scale and Performance
|
||||
|
||||
This is primarily a local/self-hosted operator platform rather than a centrally hosted multi-tenant service. Horizontal service scaling, distributed persistence, queue infrastructure, and formal load-balancing configuration were not detected.
|
||||
|
||||
Performance-sensitive areas include:
|
||||
|
||||
- LLM request latency and provider fallback
|
||||
- Mission/task timeout management
|
||||
- External tool execution
|
||||
- Multi-language source ingestion
|
||||
- Concurrent agent/operator orchestration
|
||||
- Benchmark corpus processing
|
||||
|
||||
Exact throughput, concurrent-user capacity, p95 latency, resource profiles, and installation scale are unknown. Existing timeout controls and deterministic benchmark harnesses provide a foundation for measuring these characteristics.
|
||||
|
||||
## Security, Safety, and Compliance
|
||||
|
||||
**Posture:** Strong product-level safety and verification controls for an established open-source offensive-security tool, but not evidence of a certified enterprise control environment.
|
||||
|
||||
**Controls found:**
|
||||
|
||||
- Explicit authorized-use and written-scope requirements
|
||||
- Default localhost binding for the HTTP server and Docker port
|
||||
- Localhost CORS/origin and Host-header guards
|
||||
- Target-origin-bound credential/header injection
|
||||
- Egress-scope containment for networked tools
|
||||
- Approval gating for dangerous or catalog-only tool paths
|
||||
- Environment-variable secret handling and protected local paths
|
||||
- Evidence, finding verification, claim provenance, and anti-fitting checks
|
||||
- Private vulnerability reporting through GitHub Security Advisories
|
||||
- CI lint, type, test, coverage, claim, provenance, prompt, and smoke gates
|
||||
|
||||
**Sensitive data potentially handled:** API keys, target authentication headers, vulnerability evidence, findings, captured credentials, private disclosure drafts, target metadata, and raw model/tool output.
|
||||
|
||||
**Compliance context:** The software may be used in environments subject to GDPR, CCPA, PCI DSS, HIPAA, CFAA, and local cybercrime laws, but repository references are usage guidance—not proof that T3MP3ST itself is certified for any regime.
|
||||
|
||||
## Team and Process
|
||||
|
||||
- **Repository activity:** 151 commits in the last year at analysis time
|
||||
- **Contributors:** More than ten author identities appear in the last-year history; exact active human team size is unclear because bot/agent and alias identities are mixed
|
||||
- **Branch/process model:** Pull-request and `main` push CI; exact branch-protection and reviewer requirements are not inferable from the local checkout
|
||||
- **Tests:** 75 test/spec-named files across `src/` and `scripts/`
|
||||
- **CI:** GitHub Actions runs install, lint, typecheck, tests, coverage, doctor, claim verification, anti-fitting, provenance, prompt audit, and smoke checks
|
||||
- **Documentation:** Extensive README, security policy, developer/operator guides, feature status, benchmark methodology, whitepaper, and generated docsite
|
||||
- **Release/operations:** Release checklist and operational preflight tooling exist; formal on-call, SLA, incident-management, and hosted-service procedures are unknown
|
||||
|
||||
## Dependencies and Infrastructure
|
||||
|
||||
- TypeScript/ESM on Node.js
|
||||
- Express and CORS for the local HTTP surface
|
||||
- Model Context Protocol SDK
|
||||
- Commander/Inquirer and terminal UI packages for CLI interaction
|
||||
- AJV for schema validation
|
||||
- Undici and SOCKS networking
|
||||
- Tree-sitter WASM for multi-language source ingestion
|
||||
- Vitest, ESLint, and TypeScript quality tooling
|
||||
- Docker/Docker Compose for the application and isolated challenge/tool environments
|
||||
- GitHub Actions CI
|
||||
|
||||
No Kubernetes, Terraform, service mesh, managed database, centralized cache, or message queue was detected in the analyzed repository.
|
||||
|
||||
## Known Issues and Technical Debt
|
||||
|
||||
- Stable, experimental, research, and planned capabilities coexist in one product surface, increasing expectation-management and regression risk.
|
||||
- Coordinated swarm exploitation remains less proven than the benchmarked single-agent path.
|
||||
- White-box multi-language ingestion is explicitly experimental.
|
||||
- Cloud, mobile, binary, and advanced modules remain partially scaffolded.
|
||||
- The platform can execute real offensive actions, so scope enforcement and approval boundaries are continuously high-risk code.
|
||||
- Local filesystem artifacts can contain sensitive engagement or pre-disclosure material.
|
||||
- Eighteen TODO/FIXME/HACK/XXX markers were found in `src/` and `scripts/`; each requires triage rather than being assumed defective.
|
||||
- Package and canonical tracker repository metadata point to different GitHub owners, which may confuse release provenance unless intentional and documented.
|
||||
|
||||
## Why This Intake Now?
|
||||
|
||||
The invocation supplied no additional business guidance. The evidenced purpose is to establish a current SDLC baseline from the existing codebase, preserve the distinction between shipped and aspirational capabilities, and provide a reviewable starting point for requirements, architecture, risk, and roadmap decisions.
|
||||
|
||||
## Unknowns Requiring Owner Validation
|
||||
|
||||
- Current active installations and users
|
||||
- Maintainer roles, staffing, and support model
|
||||
- Funding or commercial model
|
||||
- Production usage patterns and capacity objectives
|
||||
- Formal uptime, latency, recovery, or support commitments
|
||||
- Regulatory or contractual obligations of maintainers
|
||||
- Near-term milestone, roadmap priority, and desired investment trade-offs
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Validate the unknowns above with project owners.
|
||||
2. Review the recommended rigor and roadmap in `solution-profile.md`.
|
||||
3. Confirm priorities and trade-offs in `option-matrix.md`.
|
||||
4. If accepted, use the intake as input to an Inception or continuous architecture/risk workflow. `intake-start` is not required for this generated intake.
|
||||
@@ -0,0 +1,13 @@
|
||||
# Initial Risk Screening
|
||||
|
||||
| ID | Risk | Severity | Evidence | Mitigation / control | Status |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| R-01 | Operations exceed authorized target scope | Critical | Real network/exploitation tools | Target scope model, egress containment, approvals, scope receipts | Controlled; continuous verification |
|
||||
| R-02 | Secrets or engagement evidence leak | High | Provider keys, target headers, reports/evidence | Environment variables, target-origin binding, protected paths, local storage guidance | Open residual risk |
|
||||
| R-03 | Aspirational capability is represented as shipped | High | Broad `VISION.md`; mixed maturity surface | Status labels, claim verifier, vision-alignment matrix | Controlled; governance required |
|
||||
| R-04 | Model/tool nondeterminism produces false findings | High | LLM and external-tool execution | Ground-truth grading, finding verification, refuter/provenance gates | Open residual risk |
|
||||
| R-05 | External tools or dependencies compromise host/supply chain | High | Arsenal and container/tool installation | Narrow adapters, approval paths, pinned CI actions, isolated execution guidance | Open |
|
||||
| R-06 | Modular monolith accumulates unsafe coupling | Medium | Broad `src/` domain surface | Module boundaries, SAD, ADRs, architecture checks | Open |
|
||||
| R-07 | Local artifact loss or retention mishandling | Medium | Filesystem reports/evidence and browser localStorage | Protected update paths and operator procedures | Open |
|
||||
|
||||
No risk makes the documented current solution infeasible. R-01 is blocking for any release that weakens default containment without an approved replacement control.
|
||||
@@ -0,0 +1,109 @@
|
||||
# Solution Profile (Current System)
|
||||
|
||||
**Document type:** Existing system profile
|
||||
**Generated:** 2026-07-20
|
||||
|
||||
## Current Profile
|
||||
|
||||
**Profile:** Established production-grade open-source tool with experimental and research subsystems.
|
||||
|
||||
This classification reflects the repository rather than an unknown hosted deployment:
|
||||
|
||||
- Stable CLI, mission engine, War Room, HTTP API, MCP, arsenal, and benchmark paths are documented.
|
||||
- The project has a 1.0.0 package version, active contributors, comprehensive CI, Docker packaging, and release procedures.
|
||||
- Real network and exploitation operations create materially higher safety and security obligations than an ordinary local developer tool.
|
||||
- Several domains and coordinated-agent behaviors are still explicitly experimental, scaffolded, or research-stage.
|
||||
|
||||
## Current-State Assessment
|
||||
|
||||
### Security and Safety
|
||||
|
||||
**Level:** Strong for a self-hosted offensive-security project; enterprise certification is unverified.
|
||||
|
||||
Strengths include localhost defaults, target-bound authentication, scope containment, approvals, authorization doctrine, secret hygiene, private disclosure, provenance, and deterministic verification gates.
|
||||
|
||||
Material risks remain around dangerous tool execution, third-party binaries, target secrets, sensitive evidence, prompt/model behavior, and the gap between declared and technically enforced rules of engagement.
|
||||
|
||||
### Reliability and Observability
|
||||
|
||||
**Level:** Moderate.
|
||||
|
||||
Health endpoints, Docker health checks, timeout controls, structured mission state, smoke tests, preflight checks, and benchmark receipts are present. No repository evidence establishes production SLOs, centralized metrics/traces, alerting, fleet telemetry, backup/restore objectives, or an on-call model.
|
||||
|
||||
### Testing and Quality
|
||||
|
||||
**Level:** Strong.
|
||||
|
||||
GitHub Actions runs broad deterministic gates. The repository includes Vitest tests plus many dedicated script-level self-tests and benchmark verifiers. Coverage thresholds explicitly protect multi-language ingest files. A repository-wide coverage percentage was not assumed because the intake did not execute the full coverage suite and the configuration scopes strict thresholds to selected files.
|
||||
|
||||
### Documentation
|
||||
|
||||
**Level:** Strong.
|
||||
|
||||
The project includes operator and developer guides, API/MCP documentation, security and authorization policies, feature maturity labels, benchmark methodology, release guidance, a whitepaper, and a generated docsite.
|
||||
|
||||
### Architecture and Maintainability
|
||||
|
||||
**Level:** Moderate-to-strong.
|
||||
|
||||
The modular TypeScript structure separates orchestration, operators, tools, targets, evidence, reporting, providers, and delivery surfaces. Complexity is elevated by the broad domain surface, external-tool adapters, multiple model/provider modes, live security actions, benchmark code, and the coexistence of stable and experimental paths.
|
||||
|
||||
### Delivery and Operations
|
||||
|
||||
**Level:** Moderate.
|
||||
|
||||
Docker, GitHub Actions, release checklists, update tooling, doctor/preflight commands, and documentation publishing exist. The application is designed primarily for self-hosting; deployment automation beyond local Docker and CI is not evidenced.
|
||||
|
||||
## Recommended Profile
|
||||
|
||||
Adopt a **full SDLC rigor level for core safety boundaries and releases**, with **moderate, evidence-driven rigor for experimental modules**.
|
||||
|
||||
Core areas needing full rigor:
|
||||
|
||||
- Scope and authorization enforcement
|
||||
- Credential and evidence handling
|
||||
- Dangerous-tool approvals
|
||||
- Mission execution and target containment
|
||||
- Public benchmark and capability claims
|
||||
- Release provenance and supply-chain controls
|
||||
|
||||
Experimental modules should use lighter iteration while retaining explicit maturity labels, threat analysis, tests around shared safety boundaries, and benchmark criteria before promotion to stable.
|
||||
|
||||
## Improvement Roadmap
|
||||
|
||||
### Immediate
|
||||
|
||||
1. Validate owner-only unknowns: users, deployment patterns, support commitments, roadmap, and compliance obligations.
|
||||
2. Reconcile or document the intentional distinction between package repository metadata and the configured canonical tracker remote.
|
||||
3. Triage the 18 source/script debt markers and classify each as actionable, intentional, or obsolete.
|
||||
4. Define promotion criteria for every experimental/scaffolded domain: functional test, safety gate, benchmark receipt, docs, and rollback path.
|
||||
|
||||
### Near Term
|
||||
|
||||
1. Publish a concise architecture decision record for trust boundaries across UI/API, local agents, model providers, arsenal tools, target systems, and artifact storage.
|
||||
2. Define measurable reliability targets for local server health, mission/task timeout behavior, provider fallback, and artifact durability.
|
||||
3. Add a documented sensitive-artifact lifecycle covering retention, redaction, encryption expectations, backups, and coordinated-disclosure material.
|
||||
4. Map CI gates to risks and public claims so maintainers can see which control prevents which failure.
|
||||
|
||||
### Longer Term
|
||||
|
||||
1. Establish an explicit maturity/promotion lifecycle from scaffolded → experimental → stable.
|
||||
2. Add workload and concurrency benchmarks for mission orchestration and source ingestion.
|
||||
3. Introduce release provenance controls appropriate to the threat model, such as signed tags/artifacts and dependency/SBOM policy, if not already handled outside the repository.
|
||||
4. Revisit governance rigor when maintainer count, external integrations, hosted operation, contracts, or regulated usage grows.
|
||||
|
||||
## Tailoring
|
||||
|
||||
Recommended AIWG components:
|
||||
|
||||
- Intake, architecture decisions, risk register, security requirements, threat model, test strategy, release/deployment plan, and operational runbook
|
||||
- Continuous architecture, security-review, requirements-evolution, and risk-management workflows
|
||||
- Traceability focused on safety controls and externally advertised claims
|
||||
|
||||
Lower-value components until owner context changes:
|
||||
|
||||
- Enterprise organizational governance, legal RACI, or formal change-control boards
|
||||
- Multi-region hosted-service artifacts
|
||||
- Database migration plans for an application database that does not currently exist
|
||||
|
||||
Revisit those exclusions if the project becomes a hosted service, assumes contractual SLAs, processes centrally retained customer data, or grows into a larger formal organization.
|
||||
Reference in new issue
Block a user