claude.md

CLAUDE.md

@@ -0,0 +1,52 @@
+# Sandbox GitFlic → PT Sandbox Integration
+
+## Purpose
+Automated export of releases from GitFlic to PT Sandbox for malware analysis.
+
+## Architecture
+- `main.py` — main script with GitFlicClient, PTSandboxClient, and orchestration
+- `config.yaml` — configuration
+- `state.json` — tracks already-sent releases (prevents duplicates)
+
+## GitFlic REST API (docs.gitflic.ru)
+- **Auth**: `Authorization: token <token>` (not Bearer)
+- **Base URL (self-hosted)**: `http://<host>:<port>/rest-api`
+- **Base URL (cloud)**: `https://api.gitflic.ru`
+- **Projects**: `GET /project/shared` — returns `{"_embedded": {"projectList": [...]}, "page": {...}}`
+- **Releases**: `GET /project/{ownerAlias}/{projectAlias}/release`
+- **Pagination**: `size` (not `per_page`), `page` is 0-based
+- **IDs**: UUID strings, not integers
+- **Release fields**: `createdAt`, `tagName`, `title` (camelCase)
+- **Attachments**: in `attachmentFiles` array inside release object, `link` field is download URL
+
+## PT Sandbox REST API (help.ptsecurity.com)
+- **Auth**: `X-API-Key: <token>` header
+- **Base URL**: `https://<host>/api/v1`
+- **Endpoint**: `POST /api/v1/scan/checkFile` — upload + scan in one call
+- **Params**: `file_name=<name>&async_result=true` (query params)
+- **Body**: multipart/form-data, field name `file`
+- **Response**: `{"data": {"scan_id": "..."}, "errors": []}`
+- **License**: requires **«API с выбранными параметрами проверки»** + created **source** with same type in admin UI
+- **Token setup**: Admin UI → Sources → create "API с выбранными параметрами проверки" → API Tokens → create token linked to source with "Проверка с параметрами источника"
+- **Self-signed cert**: set `verify_ssl: false` in config; uses custom `InsecureSslAdapter`
+
+## Config Keys
+- `gitflic.base_url` — GitFlic API root
+- `gitflic.api_token` — GitFlic API token
+- `gitflic.project_source` — `all` | `list` | `company` | `team`
+- `gitflic.scan_mode` — `latest` (only newest) | `all` (all unsent)
+- `pt_sandbox.base_url` — PT Sandbox root
+- `pt_sandbox.upload_endpoint` — default `/api/v1/scan/checkFile`
+- `pt_sandbox.api_key` — PT Sandbox token
+- `pt_sandbox.verify_ssl` — `true`/`false`
+- `state.file_path` — JSON state file
+
+## Linter/Types
+- No Python type checker configured; uses basic `py_compile` for syntax validation
+- No linter configured
+
+## Common Pitfalls
+- GitFlic is NOT GitLab; don't use `/api/v1/projects` paths
+- PT Sandbox `scan/checkFile` requires a **Source** to be created in Admin UI first
+- The token must have action "Проверка с параметрами источника" enabled
+- PT Sandbox API uses 2-step flow (`uploadScanFile` → `createScanTask`) for Basic API or 1-step (`scan/checkFile`) for Source API — choose based on license