503 lines
13 KiB
Markdown
503 lines
13 KiB
Markdown
# Observation Categories for C2
|
||
|
||
This document provides comprehensive guidance on documenting observations for C4 Model Level 2 (Container) analysis.
|
||
|
||
## Observation Categories
|
||
|
||
When documenting containers, capture these observation categories:
|
||
|
||
### 1. technology
|
||
|
||
**Focus:** Technology stack, frameworks, libraries, and versions
|
||
|
||
**What to Document:**
|
||
- Primary programming language and version
|
||
- Framework name and version
|
||
- Major libraries and their purposes
|
||
- Build tools and bundlers
|
||
- Package managers
|
||
|
||
**Examples:**
|
||
- ✅ "Uses React 18.2.0 with TypeScript for type safety"
|
||
- ✅ "Built with NestJS 10.0 framework following modular architecture"
|
||
- ✅ "Python 3.11 with FastAPI for high-performance async API"
|
||
- ⚠️ "Outdated Express 3.x version (current is 4.x)" (warning)
|
||
- ⚠️ "Mixed JavaScript and TypeScript files (inconsistent)" (warning)
|
||
|
||
**Detection Commands:**
|
||
```bash
|
||
# JavaScript/TypeScript
|
||
cat package.json | jq '.dependencies'
|
||
cat package.json | jq '.devDependencies'
|
||
|
||
# Python
|
||
cat requirements.txt
|
||
pip list
|
||
|
||
# Java
|
||
cat pom.xml | grep "<dependency>"
|
||
gradle dependencies
|
||
|
||
# Check versions
|
||
node --version
|
||
python --version
|
||
java --version
|
||
```
|
||
|
||
---
|
||
|
||
### 2. runtime
|
||
|
||
**Focus:** Runtime environment, platform, and deployment model
|
||
|
||
**What to Document:**
|
||
- Runtime environment (browser, Node.js, Python, JVM, etc.)
|
||
- Platform details (OS, architecture, version)
|
||
- Containerization (Docker, Kubernetes)
|
||
- Deployment model (single instance, replicas, serverless)
|
||
- Resource constraints (CPU, memory)
|
||
|
||
**Examples:**
|
||
- ✅ "Runs in browser (Chrome 90+, Firefox 88+, Safari 14+)"
|
||
- ✅ "Node.js 18.16.0 runtime on Linux x64"
|
||
- ✅ "Containerized with Docker, deployed to Kubernetes with 3 replicas"
|
||
- ✅ "Serverless deployment on AWS Lambda with cold start ~500ms"
|
||
- ⚠️ "No resource limits configured in Kubernetes" (warning)
|
||
|
||
**Detection Commands:**
|
||
```bash
|
||
# Check Dockerfile
|
||
cat Dockerfile | grep "FROM"
|
||
|
||
# Check K8s deployment
|
||
kubectl get deployment <name> -o yaml | grep replicas
|
||
|
||
# Check docker-compose
|
||
cat docker-compose.yml | grep "image:\|build:"
|
||
|
||
# Check runtime config
|
||
cat .node-version
|
||
cat runtime.txt
|
||
```
|
||
|
||
---
|
||
|
||
### 3. communication
|
||
|
||
**Focus:** How the container communicates with other containers
|
||
|
||
**What to Document:**
|
||
- Communication protocols (HTTP, gRPC, WebSocket, etc.)
|
||
- API specifications (REST, GraphQL)
|
||
- Message brokers (RabbitMQ, Kafka)
|
||
- Synchronous vs asynchronous
|
||
- Authentication mechanisms
|
||
|
||
**Examples:**
|
||
- ✅ "Communicates with API via HTTP REST over HTTPS"
|
||
- ✅ "Publishes events to RabbitMQ message broker"
|
||
- ✅ "Uses gRPC for inter-service communication"
|
||
- ✅ "WebSocket connection for real-time updates"
|
||
- ⚠️ "HTTP communication not encrypted (uses http://)" (warning)
|
||
|
||
**Detection Commands:**
|
||
```bash
|
||
# Find HTTP clients
|
||
grep -r "axios\|fetch\|requests" src/
|
||
|
||
# Find gRPC
|
||
grep -r "grpc\|proto" src/ | head -5
|
||
|
||
# Find WebSocket
|
||
grep -r "socket.io\|ws\|websocket" src/
|
||
|
||
# Find message broker
|
||
grep -r "amqp\|kafka\|redis.*publish" src/
|
||
```
|
||
|
||
---
|
||
|
||
### 4. data-storage
|
||
|
||
**Focus:** Data persistence, caching, and storage patterns
|
||
|
||
**What to Document:**
|
||
- Database type and version (PostgreSQL, MongoDB, etc.)
|
||
- Connection pooling configuration
|
||
- Caching strategy (Redis, Memcached)
|
||
- File storage (S3, local filesystem)
|
||
- Stateful vs stateless
|
||
|
||
**Examples:**
|
||
- ✅ "PostgreSQL 15 database with connection pooling (max 20)"
|
||
- ✅ "Redis cache for session storage with 1-hour TTL"
|
||
- ✅ "Stores uploaded files in AWS S3 bucket"
|
||
- ✅ "No database connection (stateless API)"
|
||
- ⚠️ "Database connection pool not configured (potential bottleneck)" (warning)
|
||
|
||
**Detection Commands:**
|
||
```bash
|
||
# Find database connections
|
||
grep -r "DATABASE_URL\|DB_HOST" .env
|
||
|
||
# Find ORMs
|
||
grep -r "prisma\|typeorm\|sequelize\|sqlalchemy" .
|
||
|
||
# Find cache usage
|
||
grep -r "REDIS_URL\|redis.get\|redis.set" .
|
||
|
||
# Find file storage
|
||
grep -r "S3_BUCKET\|aws-sdk.*s3\|multer" .
|
||
```
|
||
|
||
---
|
||
|
||
### 5. authentication
|
||
|
||
**Focus:** Authentication and authorization mechanisms
|
||
|
||
**What to Document:**
|
||
- Authentication method (JWT, OAuth, API keys)
|
||
- Token expiry and refresh
|
||
- Authorization rules (RBAC, ABAC)
|
||
- Session management
|
||
- Security headers
|
||
|
||
**Examples:**
|
||
- ✅ "JWT Bearer token authentication with 15-minute expiry"
|
||
- ✅ "OAuth 2.0 integration with Auth0"
|
||
- ✅ "API key authentication via x-api-key header"
|
||
- ⚠️ "No authentication implemented" (warning)
|
||
- 🔴 "JWT tokens never expire (security risk)" (critical)
|
||
|
||
**Detection Commands:**
|
||
```bash
|
||
# Find authentication libraries
|
||
grep -r "passport\|jsonwebtoken\|auth0" package.json
|
||
|
||
# Find JWT usage
|
||
grep -r "jwt\|bearer\|token" src/ | grep -i auth
|
||
|
||
# Find OAuth
|
||
grep -r "oauth\|openid" .
|
||
|
||
# Check for API keys
|
||
grep -r "API_KEY\|X-API-KEY" .env
|
||
```
|
||
|
||
---
|
||
|
||
### 6. configuration
|
||
|
||
**Focus:** Configuration management and environment variables
|
||
|
||
**What to Document:**
|
||
- Configuration sources (.env, ConfigMap, Secrets)
|
||
- Environment-specific configs (dev, staging, prod)
|
||
- Secret management
|
||
- Configuration validation
|
||
- Default values
|
||
|
||
**Examples:**
|
||
- ✅ "Configuration via environment variables"
|
||
- ✅ "Uses .env files for local development"
|
||
- ✅ "ConfigMap and Secrets in Kubernetes"
|
||
- ⚠️ "Hardcoded configuration values in source code" (warning)
|
||
- 🔴 "Secrets committed to git repository" (critical)
|
||
|
||
**Detection Commands:**
|
||
```bash
|
||
# Find .env files
|
||
find . -name ".env*" -not -path "*/node_modules/*"
|
||
|
||
# Check for ConfigMap usage
|
||
grep -r "ConfigMap" k8s/
|
||
|
||
# Find hardcoded values
|
||
grep -r "http://\|https://\|mongodb://\|postgres://" src/ | grep -v ".env"
|
||
|
||
# Check for secret management
|
||
grep -r "vault\|doppler\|aws-secrets-manager" .
|
||
```
|
||
|
||
---
|
||
|
||
### 7. monitoring
|
||
|
||
**Focus:** Logging, monitoring, and observability
|
||
|
||
**What to Document:**
|
||
- Logging framework and destination
|
||
- Metrics collection (Prometheus, DataDog)
|
||
- Tracing (OpenTelemetry, Jaeger)
|
||
- Health checks and readiness probes
|
||
- Error tracking (Sentry, Rollbar)
|
||
|
||
**Examples:**
|
||
- ✅ "Application logs to stdout, collected by Fluentd"
|
||
- ✅ "Prometheus metrics exposed on /metrics endpoint"
|
||
- ✅ "OpenTelemetry tracing enabled"
|
||
- ⚠️ "No logging or monitoring configured" (warning)
|
||
- ⚠️ "Logs contain sensitive data (PII, credentials)" (warning)
|
||
|
||
**Detection Commands:**
|
||
```bash
|
||
# Find logging libraries
|
||
grep -r "winston\|pino\|bunyan\|logrus" package.json
|
||
|
||
# Find metrics
|
||
grep -r "prometheus\|statsd\|datadog" .
|
||
|
||
# Find tracing
|
||
grep -r "opentelemetry\|jaeger\|zipkin" .
|
||
|
||
# Check for health endpoints
|
||
grep -r "/health\|/ready\|/alive" src/
|
||
```
|
||
|
||
---
|
||
|
||
### 8. dependencies
|
||
|
||
**Focus:** External dependencies and third-party services
|
||
|
||
**What to Document:**
|
||
- Third-party API integrations (Stripe, SendGrid)
|
||
- External service dependencies
|
||
- SDK usage
|
||
- Vendor lock-in risks
|
||
- Availability dependencies
|
||
|
||
**Examples:**
|
||
- ✅ "Depends on Stripe API for payment processing"
|
||
- ✅ "Uses SendGrid for transactional email"
|
||
- ✅ "Integrates with Google Analytics for tracking"
|
||
- ⚠️ "Heavy dependency on external APIs (availability risk)" (warning)
|
||
- ⚠️ "No fallback for third-party service failures" (warning)
|
||
|
||
**Detection Commands:**
|
||
```bash
|
||
# Find third-party SDKs
|
||
grep -r "stripe\|twilio\|sendgrid\|mailgun" package.json
|
||
|
||
# Find external API calls
|
||
grep -r "https://api\." src/ .env
|
||
|
||
# Check for API keys
|
||
grep -r "STRIPE_KEY\|TWILIO_\|SENDGRID_" .env
|
||
|
||
# Find vendor-specific code
|
||
grep -r "aws-sdk\|google-cloud\|azure" .
|
||
```
|
||
|
||
---
|
||
|
||
## Observation Structure
|
||
|
||
### JSON Schema
|
||
|
||
```json
|
||
{
|
||
"id": "obs-tech-react-18",
|
||
"category": "technology",
|
||
"severity": "info",
|
||
"description": "React 18.2.0 with TypeScript 5.0 for type-safe component development",
|
||
"evidence": {
|
||
"type": "file",
|
||
"location": "package.json",
|
||
"snippet": "\"react\": \"^18.2.0\", \"typescript\": \"^5.0.0\""
|
||
},
|
||
"tags": ["react", "typescript", "frontend", "spa"],
|
||
"discovered_at": "2025-01-15T10:30:00Z",
|
||
"discovered_by": "c2-abstractor"
|
||
}
|
||
```
|
||
|
||
### Field Descriptions
|
||
|
||
- **id**: Unique identifier (format: `obs-<category>-<short-desc>`)
|
||
- **category**: One of the 8 categories above
|
||
- **severity**: `info`, `warning`, or `critical`
|
||
- **description**: Human-readable observation
|
||
- **evidence**: Proof of the observation
|
||
- **type**: `file`, `command`, `inference`
|
||
- **location**: File path, command, or reasoning
|
||
- **snippet**: Code snippet, command output, or explanation
|
||
- **tags**: Searchable keywords
|
||
- **discovered_at**: ISO 8601 timestamp
|
||
- **discovered_by**: Tool or agent name
|
||
|
||
---
|
||
|
||
## Observation Severity Levels
|
||
|
||
### info (Informational)
|
||
|
||
**Purpose:** Neutral findings documenting the system as it is
|
||
|
||
**Examples:**
|
||
- ℹ️ "Uses Prisma ORM for database access"
|
||
- ℹ️ "React 18.2.0 with functional components and hooks"
|
||
- ℹ️ "Deployed with 3 replicas for high availability"
|
||
|
||
**When to Use:**
|
||
- Technology choices (neutral)
|
||
- Architecture patterns (no issues)
|
||
- Configuration details (standard)
|
||
|
||
### warning (Needs Attention)
|
||
|
||
**Purpose:** Potential issues that should be addressed but aren't blocking
|
||
|
||
**Examples:**
|
||
- ⚠️ "Redis cache has no password configured"
|
||
- ⚠️ "Outdated Express 3.x version (current is 4.x)"
|
||
- ⚠️ "No resource limits configured in Kubernetes"
|
||
- ⚠️ "Logs contain timestamps but no correlation IDs"
|
||
|
||
**When to Use:**
|
||
- Outdated dependencies
|
||
- Missing best practices
|
||
- Potential performance issues
|
||
- Missing recommended features
|
||
|
||
### critical (Immediate Action)
|
||
|
||
**Purpose:** Critical issues requiring immediate action (security, stability)
|
||
|
||
**Examples:**
|
||
- 🔴 "Database credentials hardcoded in source code"
|
||
- 🔴 "JWT tokens never expire (security risk)"
|
||
- 🔴 "API exposed without authentication"
|
||
- 🔴 "Secrets committed to git repository"
|
||
|
||
**When to Use:**
|
||
- Security vulnerabilities
|
||
- Data exposure risks
|
||
- Critical misconfigurations
|
||
- Blocking production issues
|
||
|
||
---
|
||
|
||
## Best Practices
|
||
|
||
### DO:
|
||
|
||
1. **Be specific** - Include versions, exact technologies
|
||
2. **Provide evidence** - Link to files, commands, or reasoning
|
||
3. **Use consistent format** - Follow the JSON schema
|
||
4. **Tag appropriately** - Use searchable, relevant tags
|
||
5. **Document warnings** - Call out anti-patterns and risks
|
||
6. **Cite sources** - Reference configuration files, code
|
||
|
||
### DON'T:
|
||
|
||
1. **Don't be vague** - "Uses React" → "Uses React 18.2.0"
|
||
2. **Don't skip evidence** - Always provide proof
|
||
3. **Don't over-categorize** - One observation = one category
|
||
4. **Don't ignore security** - Flag security issues as critical
|
||
5. **Don't duplicate** - Consolidate similar observations
|
||
6. **Don't guess** - Only document what you can verify
|
||
|
||
---
|
||
|
||
## Common Observation Patterns
|
||
|
||
### Pattern: Outdated Dependencies
|
||
|
||
```json
|
||
{
|
||
"id": "obs-tech-outdated-express",
|
||
"category": "technology",
|
||
"severity": "warning",
|
||
"description": "Express 3.x is significantly outdated (current stable: 4.x). Consider upgrading for security patches and new features.",
|
||
"evidence": {
|
||
"type": "file",
|
||
"location": "package.json",
|
||
"snippet": "\"express\": \"^3.21.2\""
|
||
},
|
||
"tags": ["express", "outdated", "dependency", "security"]
|
||
}
|
||
```
|
||
|
||
### Pattern: Missing Authentication
|
||
|
||
```json
|
||
{
|
||
"id": "obs-auth-missing",
|
||
"category": "authentication",
|
||
"severity": "critical",
|
||
"description": "API endpoints exposed without authentication. All routes are publicly accessible.",
|
||
"evidence": {
|
||
"type": "command",
|
||
"location": "grep -r 'app.get\\|app.post' src/",
|
||
"snippet": "No authentication middleware found in route definitions"
|
||
},
|
||
"tags": ["authentication", "security", "api", "critical"]
|
||
}
|
||
```
|
||
|
||
### Pattern: Performance Configuration
|
||
|
||
```json
|
||
{
|
||
"id": "obs-runtime-no-limits",
|
||
"category": "runtime",
|
||
"severity": "warning",
|
||
"description": "Kubernetes deployment has no CPU or memory limits configured, which may lead to resource contention.",
|
||
"evidence": {
|
||
"type": "file",
|
||
"location": "k8s/deployment.yaml",
|
||
"snippet": "No 'resources.limits' section found in container spec"
|
||
},
|
||
"tags": ["kubernetes", "resources", "performance", "deployment"]
|
||
}
|
||
```
|
||
|
||
### Pattern: Good Practice
|
||
|
||
```json
|
||
{
|
||
"id": "obs-monitor-prometheus",
|
||
"category": "monitoring",
|
||
"severity": "info",
|
||
"description": "Prometheus metrics endpoint exposed at /metrics with custom application metrics",
|
||
"evidence": {
|
||
"type": "file",
|
||
"location": "src/metrics.ts",
|
||
"snippet": "app.get('/metrics', (req, res) => { res.set('Content-Type', register.contentType); res.end(register.metrics()); });"
|
||
},
|
||
"tags": ["prometheus", "monitoring", "metrics", "observability"]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Relationship to C1 Observations
|
||
|
||
C2 observations are **more detailed** than C1:
|
||
|
||
| Aspect | C1 (System) | C2 (Container) |
|
||
|--------|-------------|----------------|
|
||
| **Scope** | Entire system | Individual containers |
|
||
| **Technology** | High-level tech stack | Specific frameworks & versions |
|
||
| **Runtime** | General deployment | Exact runtime config |
|
||
| **Communication** | External dependencies | Inter-container protocols |
|
||
|
||
**Example:**
|
||
- **C1**: "E-Commerce System uses Node.js and React"
|
||
- **C2 (Frontend)**: "React 18.2.0 SPA with TypeScript 5.0, deployed to Vercel"
|
||
- **C2 (Backend)**: "NestJS 10.0 API on Node.js 18.16.0, containerized in Kubernetes with 3 replicas"
|
||
|
||
---
|
||
|
||
## Next Steps
|
||
|
||
After capturing observations:
|
||
|
||
1. **Validate** using melly-validation scripts
|
||
2. **Store** in basic-memory MCP knowledge base
|
||
3. **Reference** in container documentation
|
||
4. **Track** warnings and critical issues
|
||
5. **Update** as system evolves
|