sandbox-gitflic/CLAUDE.md

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