# 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