Skip to content
This repository was archived by the owner on Jun 2, 2026. It is now read-only.

Commit d10fc10

Browse files
fopinafopina
authored
more integration tests (#41)
1 parent 055689f commit d10fc10

3 files changed

Lines changed: 366 additions & 9 deletions

File tree

‎AGENTS.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# AGENTS.md
2+
3+
## Project summary
4+
5+
This repository publishes a generated Python client for the DefectDojo v2 API.
6+
7+
- Runtime package: `defectdojo_api_generated`
8+
- Primary public entry point: `defectdojo_api_generated.client.DefectDojo`
9+
- Generator source: OpenAPI Generator with custom mustache templates under `support/api_generation/custom_templates`
10+
- Upstream schema source: DefectDojo OpenAPI schema fetched and lightly patched under `support/openapi`
11+
12+
The codebase is mostly generated. The important mental model is:
13+
14+
1. Fetch or refresh the OpenAPI schema.
15+
2. Apply small schema tweaks that add generator hints.
16+
3. Regenerate the package and generated tests.
17+
4. Keep handwritten customization in templates or helper modules, not in generated API/model files.
18+
19+
## Repo layout
20+
21+
### Generated runtime package
22+
23+
- `defectdojo_api_generated/api/`
24+
One generated class per API area. These files are large and should be treated as generated output.
25+
- `defectdojo_api_generated/models/`
26+
Generated Pydantic request/response models.
27+
- `defectdojo_api_generated/__init__.py`
28+
Generated package export surface and version metadata.
29+
- `defectdojo_api_generated/api_client.py`
30+
Generated HTTP client core.
31+
- `defectdojo_api_generated/configuration.py`, `rest.py`, `exceptions.py`, `api_response.py`
32+
Generated runtime plumbing.
33+
34+
### Handwritten or customized runtime pieces
35+
36+
- `defectdojo_api_generated/client.py`
37+
Custom convenience wrapper exposing lazily constructed `*_api` properties and simpler auth setup.
38+
- `defectdojo_api_generated/helpers.py`
39+
Handwritten pagination helper used by generated iterator methods.
40+
41+
### Generation pipeline
42+
43+
- `support/openapi/fetch_openapi.py`
44+
Fetches the DefectDojo schema from either the live demo or a local Docker-backed instance.
45+
- `support/openapi/tweak_openapi.py`
46+
Adds custom vendor extensions for paginated endpoints so generated API classes expose iterator helpers.
47+
- `support/openapi/openapi.json`
48+
Stored raw schema snapshot.
49+
- `support/openapi/build/openapi.json`
50+
Tweaked schema used for generation.
51+
- `support/api_generation/generate.sh`
52+
Runs schema tweaking, OpenAPI Generator, and moves generated tests into `tests/generated/`.
53+
- `support/api_generation/config.yaml`
54+
OpenAPI Generator config.
55+
- `support/api_generation/custom_templates/`
56+
The real customization layer. If generation behavior needs to change, edit templates here rather than the generated output.
57+
- `support/api_generation/templates.spec/`
58+
Reference snapshot of template files.
59+
60+
### Tests
61+
62+
- `tests/generated/`
63+
Generated smoke tests for API and model classes. Expect these to be overwritten on regeneration.
64+
- `tests/unit/`
65+
Small handwritten unit tests for custom client behavior.
66+
- `tests/integration/`
67+
End-to-end tests against a real DefectDojo instance.
68+
- `tests/data/`
69+
Fixtures for integration scenarios, such as import/reimport payloads.
70+
71+
### Local integration environment
72+
73+
- `support/integration/docker-compose.yml`
74+
Local DefectDojo stack for schema refreshes and integration testing.
75+
- `support/integration/run_dojo.sh`
76+
Starts the stack and waits for the API to become ready.
77+
- `support/integration/stop_dojo.sh`
78+
Stops the stack.
79+
80+
## How the client works
81+
82+
The package is intentionally thin:
83+
84+
- `DefectDojo(...)` builds a `Configuration`, infers proxy settings from the environment, and creates one shared `ApiClient`.
85+
- Each `*.api` property on `DefectDojo` returns a generated API wrapper bound to that shared client.
86+
- Generated API methods serialize parameters, call the generated `ApiClient`, then deserialize into Pydantic models.
87+
- For paginated GET endpoints, `support/openapi/tweak_openapi.py` annotates the schema with `x-has-iterator`, and the custom `api.mustache` template emits `*_iterator()` helpers that stream results across pages via `helpers.get_all_pages()`.
88+
89+
## Safe editing rules
90+
91+
Prefer these rules unless a task explicitly requires regeneration:
92+
93+
- Do not hand-edit files in `defectdojo_api_generated/api/`.
94+
- Do not hand-edit files in `defectdojo_api_generated/models/`.
95+
- Treat `tests/generated/` as generated output.
96+
- If a change should survive regeneration, make it in:
97+
- `support/api_generation/custom_templates/`
98+
- `support/openapi/tweak_openapi.py`
99+
- `support/openapi/fetch_openapi.py`
100+
- `defectdojo_api_generated/helpers.py`
101+
- `defectdojo_api_generated/client.py`
102+
- handwritten tests in `tests/unit/` or `tests/integration/`
103+
104+
When deciding where to edit:
105+
106+
- API signature/serialization/runtime generation issue: fix a mustache template or schema tweak.
107+
- Pagination iteration issue: check `tweak_openapi.py`, `custom_templates/api.mustache`, and `helpers.py`.
108+
- Convenience client/auth/proxy behavior: check `client.py`.
109+
- Upstream API shape drift: refresh schema, regenerate, then review diffs.
110+
111+
## Common commands
112+
113+
Environment:
114+
115+
- `uv sync --dev`
116+
117+
Formatting and lint:
118+
119+
- `make lint`
120+
- `make lint-check`
121+
122+
Tests:
123+
124+
- `make test`
125+
- `make test-e2e`
126+
127+
Schema and generation:
128+
129+
- `make schema`
130+
- `make generate`
131+
- `make templates`
132+
133+
Publishing helper:
134+
135+
- `make testpub`
136+
137+
## Regeneration workflow
138+
139+
Use this when the DefectDojo API changed or when template/schema customizations need to be applied across the client:
140+
141+
1. Refresh dependencies with `uv sync --dev`.
142+
2. Fetch schema with `make schema` or run `support/openapi/fetch_openapi.py --demo`.
143+
3. Regenerate with `make generate`.
144+
4. Review diffs carefully in:
145+
- `defectdojo_api_generated/`
146+
- `tests/generated/`
147+
5. Run `make test`.
148+
6. If integration behavior changed, run `make test-e2e`.
149+
150+
## CI and release notes
151+
152+
- CI runs lint, unit tests on multiple Python versions, and integration tests via GitHub Actions.
153+
- Packaging metadata lives in `pyproject.toml`.
154+
- Release publishing is tag-driven via `.github/workflows/publish-main.yml`.
155+
- The package targets Python `>=3.9,<4`.
156+
157+
## Practical contributor notes
158+
159+
- The repository currently includes generated artifacts and some local cache directories; focus changes on tracked source files.
160+
- `README.md` is minimal and points contributors to `CONTRIBUTING.md`; this file is the better quick orientation for agentic work.
161+
- If generated output and handwritten files disagree, assume templates and schema-tweaking scripts are the source of truth, then regenerate instead of patching the generated leaf files by hand.

‎tests/data/semgrep_report.json‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
{
2+
"results": [
3+
{
4+
"check_id": "java.lang.security.audit.cbc-padding-oracle.cbc-padding-oracle",
5+
"path": "src/main/java/org/owasp/benchmark/testcode/BenchmarkTest02194.java",
6+
"start": {
7+
"line": 64,
8+
"col": 4
9+
},
10+
"end": {
11+
"line": 64,
12+
"col": 83
13+
},
14+
"extra": {
15+
"message": "Using CBC with PKCS5Padding is susceptible to padding orcale attacks. A malicious actor\ncould discern the difference between plaintext with valid or invalid padding. Further,\nCBC mode does not include any integrity checks. See https://find-sec-bugs.github.io/bugs.htm#CIPHER_INTEGRITY.\nUse 'AES/GCM/NoPadding' instead.\n",
16+
"metavars": {
17+
"$CIPHER": {
18+
"start": {
19+
"line": 64,
20+
"col": 28,
21+
"offset": 2336
22+
},
23+
"end": {
24+
"line": 64,
25+
"col": 47,
26+
"offset": 2355
27+
},
28+
"abstract_content": "javax crypto Cipher",
29+
"unique_id": {
30+
"type": "AST",
31+
"md5sum": "aab127507f3afdb7377ad511a669b91c"
32+
}
33+
}
34+
},
35+
"metadata": {
36+
"cwe": "CWE-696: Incorrect Behavior Order",
37+
"owasp": "A3: Sensitive Data Exposure",
38+
"source-rule-url": "https://find-sec-bugs.github.io/bugs.htm#PADDING_ORACLE",
39+
"references": [
40+
"https://capec.mitre.org/data/definitions/463.html"
41+
]
42+
},
43+
"severity": "WARNING",
44+
"fix": "javax crypto Cipher.getInstance(\"AES/GCM/NoPadding\");",
45+
"lines": "\t\t\tjavax.crypto.Cipher c = javax.crypto.Cipher.getInstance(\"DES/CBC/PKCS5Padding\");"
46+
}
47+
},
48+
{
49+
"check_id": "java.lang.security.audit.cbc-padding-oracle.cbc-padding-oracle",
50+
"path": "src/main/java/org/owasp/benchmark/testcode/BenchmarkTest02195.java",
51+
"start": {
52+
"line": 64,
53+
"col": 4
54+
},
55+
"end": {
56+
"line": 64,
57+
"col": 83
58+
},
59+
"extra": {
60+
"message": "Using CBC with PKCS5Padding is susceptible to padding orcale attacks. A malicious actor\ncould discern the difference between plaintext with valid or invalid padding. Further,\nCBC mode does not include any integrity checks. See https://find-sec-bugs.github.io/bugs.htm#CIPHER_INTEGRITY.\nUse 'AES/GCM/NoPadding' instead.\n",
61+
"metavars": {
62+
"$CIPHER": {
63+
"start": {
64+
"line": 64,
65+
"col": 28,
66+
"offset": 2336
67+
},
68+
"end": {
69+
"line": 64,
70+
"col": 47,
71+
"offset": 2355
72+
},
73+
"abstract_content": "javax crypto Cipher",
74+
"unique_id": {
75+
"type": "AST",
76+
"md5sum": "aab127507f3afdb7377ad511a669b91c"
77+
}
78+
}
79+
},
80+
"metadata": {
81+
"cwe": "CWE-696: Incorrect Behavior Order",
82+
"owasp": "A3: Sensitive Data Exposure",
83+
"source-rule-url": "https://find-sec-bugs.github.io/bugs.htm#PADDING_ORACLE",
84+
"references": [
85+
"https://capec.mitre.org/data/definitions/463.html"
86+
]
87+
},
88+
"severity": "WARNING",
89+
"fix": "javax crypto Cipher.getInstance(\"AES/GCM/NoPadding\");",
90+
"lines": "\t\t\tjavax.crypto.Cipher c = javax.crypto.Cipher.getInstance(\"DES/CBC/PKCS5Padding\");"
91+
}
92+
},
93+
{
94+
"check_id": "java.lang.security.audit.cbc-padding-oracle.cbc-padding-oracle",
95+
"path": "src/main/java/org/owasp/benchmark/testcode/BenchmarkTest01150.java",
96+
"start": {
97+
"line": 66,
98+
"col": 4
99+
},
100+
"end": {
101+
"line": 66,
102+
"col": 83
103+
},
104+
"extra": {
105+
"message": "Using CBC with PKCS5Padding is susceptible to padding orcale attacks. A malicious actor\ncould discern the difference between plaintext with valid or invalid padding. Further,\nCBC mode does not include any integrity checks. See https://find-sec-bugs.github.io/bugs.htm#CIPHER_INTEGRITY.\nUse 'AES/GCM/NoPadding' instead.\n",
106+
"metavars": {
107+
"$CIPHER": {
108+
"start": {
109+
"line": 66,
110+
"col": 28,
111+
"offset": 2513
112+
},
113+
"end": {
114+
"line": 66,
115+
"col": 47,
116+
"offset": 2532
117+
},
118+
"abstract_content": "javax crypto Cipher",
119+
"unique_id": {
120+
"type": "AST",
121+
"md5sum": "aab127507f3afdb7377ad511a669b91c"
122+
}
123+
}
124+
},
125+
"metadata": {
126+
"cwe": "CWE-696: Incorrect Behavior Order",
127+
"owasp": "A3: Sensitive Data Exposure",
128+
"source-rule-url": "https://find-sec-bugs.github.io/bugs.htm#PADDING_ORACLE",
129+
"references": [
130+
"https://capec.mitre.org/data/definitions/463.html"
131+
]
132+
},
133+
"severity": "INFO",
134+
"fix": "javax crypto Cipher.getInstance(\"AES/GCM/NoPadding\");",
135+
"lines": "\t\t\tjavax.crypto.Cipher c = javax.crypto.Cipher.getInstance(\"DES/CBC/PKCS5Padding\");"
136+
}
137+
}
138+
],
139+
"errors": []
140+
}

0 commit comments

Comments
 (0)