Skip to content

Commit f26e116

Browse files
sei-renaesei-renae
authored
✨ Set up GitHub Copilot instructions for SSVC repository (#1012)
Go team
2 parents c032b5d + 84a9767 commit f26e116

File tree

2 files changed

+170
-0
lines changed

2 files changed

+170
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
# GitHub Copilot Instructions for SSVC
2+
3+
This repository contains the **Stakeholder-Specific Vulnerability Categorization (SSVC)** project, which provides a system for prioritizing actions during vulnerability management.
4+
5+
## Project Overview
6+
7+
SSVC is a modular decision-making framework for vulnerability management that includes:
8+
- Python modules for decision points, decision tables, and outcomes
9+
- MkDocs-based documentation website
10+
- Interactive calculators and policy explorers
11+
- JSON/CSV data files for decision tables
12+
- Docker and Make-based development and deployment
13+
14+
## Technology Stack
15+
16+
- **Primary Language**: Python 3.x
17+
- **Package Management**: uv (package and project manager)
18+
- **Build Tool**: Make
19+
- **Documentation**: MkDocs with Material theme
20+
- **Testing**: pytest
21+
- **Data Models**: Pydantic for JSON schema validation
22+
- **Scientific Computing**: NumPy, SciPy, scikit-learn
23+
- **Web Framework**: FastAPI (for API endpoints)
24+
- **Containerization**: Docker and Docker Compose
25+
26+
## Project Structure
27+
28+
- `/src/ssvc/` - Core Python modules for SSVC functionality
29+
- `decision_points/` - Decision point definitions
30+
- `decision_tables/` - Decision table implementations
31+
- `api/` - FastAPI application
32+
- `outcomes/` - Outcome definitions
33+
- `dp_groups/` - Decision point groups
34+
- `registry/` - Registry functionality
35+
- `/docs/` - Markdown documentation source files
36+
- `/data/` - JSON and CSV data files for decision tables
37+
- `/src/test/` - Unit tests
38+
- `/docker/` - Docker configurations
39+
- `/obsolete/` - Deprecated code (do not modify)
40+
41+
## Make Commands
42+
43+
Use `make help` to see all available commands. Common targets include:
44+
45+
- `make dev` - Set up development environment
46+
- `make test` - Run tests locally
47+
- `make docker_test` - Run tests in Docker
48+
- `make docs_local` - Serve documentation locally (http://localhost:8000/SSVC/)
49+
- `make docs` - Build and run documentation in Docker
50+
- `make api_dev` - Run API locally with auto-reload
51+
- `make api` - Build and run API in Docker
52+
- `make mdlint_fix` - Run markdown linting with auto-fix
53+
- `make regenerate_json` - Regenerate JSON files from Python modules
54+
55+
## Development Workflow
56+
57+
## Coding Conventions
58+
59+
### Python Code
60+
61+
- Follow PEP 8 style guidelines
62+
- Use type hints for function signatures and return types
63+
- Use Pydantic models for data validation
64+
- Document classes and functions with docstrings
65+
- Prefer explicit imports over wildcard imports
66+
- Module structure uses absolute imports from `ssvc` package
67+
68+
### Naming Conventions
69+
70+
- Python files: `snake_case.py`
71+
- Classes: `PascalCase`
72+
- Functions/variables: `snake_case`
73+
- Constants: `UPPER_SNAKE_CASE`
74+
75+
## Testing Requirements
76+
77+
### Test Structure
78+
79+
- Unit tests use pytest framework
80+
- Tests are located in `/src/test/`
81+
- Test files follow pattern: `test_*.py`
82+
- Run tests with: `make test` or `uv run pytest -v`
83+
84+
### Test Coverage
85+
86+
- Write tests for new Python modules
87+
- Ensure decision points and tables have corresponding tests
88+
- Test JSON schema validation
89+
- Validate data model serialization/deserialization
90+
91+
### Before Committing
92+
93+
1. Run all tests: `make test`
94+
2. Ensure no test failures
95+
3. Fix any linting issues: `make mdlint_fix`
96+
4. Verify documentation builds: `make docs_local`
97+
98+
## Documentation
99+
100+
### Writing Documentation
101+
102+
- Documentation uses MkDocs with Material theme
103+
- Files are in Markdown format in `/docs/`
104+
- Use Python exec blocks for dynamic content generation
105+
- Include examples and code snippets
106+
- Follow existing documentation structure
107+
108+
### Documentation Features
109+
110+
- Automatic API documentation via mkdocstrings
111+
- Python module imports for dynamic content generation
112+
- BibTeX citations via mkdocs-bibtex
113+
- Add markdown files to site navigation by specifying them in `mkdocs.yml`
114+
- Include markdown files in other markdown files with `mkdocs-include-markdown-plugin`
115+
- Dynamically generate content from python code blocks using the `markdown-exec` plugin
116+
117+
## Data Files
118+
119+
### JSON Files
120+
121+
- Located in `/data/json/`
122+
- Generated from Python Pydantic models
123+
- Use JSON schema validation
124+
125+
### CSV Files
126+
127+
- Located in `/data/csv/`
128+
- Define decision table outcomes
129+
- Generated from python modules (The python data objects are authoritative)
130+
- Allows users to explore customizing SSVC for specific environments
131+
132+
## Common Pitfalls
133+
134+
1. **Import Paths**: Use absolute imports like `from ssvc.module import Class`, not relative imports
135+
2. **PYTHONPATH**: When running scripts directly, set `export PYTHONPATH=$PYTHONPATH:$(pwd)/src`
136+
3. **JSON Regeneration**: After modifying decision points/tables, regenerate JSON with `make regenerate_json`
137+
4. **Docker Context**: Some make targets use Docker, others run locally - check the Makefile
138+
5. **Package Management**: Use `make` commands or `uv` directly, not pip
139+
6. **Obsolete Code and Documentation**: Never modify files in `/obsolete/`, `/doc/`, or `/pdfs/` directories
140+
141+
## API Development
142+
143+
- FastAPI application is in `/src/ssvc/api/`
144+
- Run locally with auto-reload: `make api_dev` (serves on http://127.0.0.1:8000/docs)
145+
- Run in Docker: `make api` (serves on http://127.0.0.1:8001/SSVC/)
146+
147+
## Git Workflow
148+
149+
- Create feature branches for new work
150+
- Write descriptive commit messages
151+
- Reference issue numbers in commits when applicable
152+
- Keep commits focused and atomic
153+
- Run tests before pushing
154+
155+
## Additional Resources
156+
157+
- Main documentation: https://certcc.github.io/SSVC/
158+
- Source repository: https://github.com/CERTCC/SSVC
159+
- SSVC Calculator: https://certcc.github.io/SSVC/ssvc-calc/
160+
- Contributing guide: See CONTRIBUTING.md
161+
- Project wiki: https://github.com/CERTCC/SSVC/wiki
162+
163+
## Special Notes
164+
165+
- This project uses a MIT (SEI)-style license with Carnegie Mellon University copyright (see LICENSE file)
166+
- Decision points and tables follow SSVC specification
167+
- Backward compatibility is important for existing data files
168+
- Documentation changes should be reflected in both `/docs/` and `/src/README.md` when applicable

‎.markdownlint.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
ignores:
2+
- .github/**
13
default: true
24
# disable noisy rules
35
# 0004 Unordered List style

0 commit comments

Comments
 (0)