{"id":31581487,"url":"https://github.com/cyphercoderr/stacksync-assesment","last_synced_at":"2026-05-15T22:31:09.712Z","repository":{"id":316826375,"uuid":"1064971441","full_name":"cyphercoderr/StackSync-Assesment","owner":"cyphercoderr","description":"StackSync Assesment ... done using flask, nsjail,sandbox,docker and cloud.","archived":false,"fork":false,"pushed_at":"2025-09-26T23:01:41.000Z","size":24,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-27T00:23:11.074Z","etag":null,"topics":["api","flask","flask-application","nsjail","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cyphercoderr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-26T21:04:02.000Z","updated_at":"2025-09-26T23:01:44.000Z","dependencies_parsed_at":"2025-09-27T08:03:15.691Z","dependency_job_id":null,"html_url":"https://github.com/cyphercoderr/StackSync-Assesment","commit_stats":null,"previous_names":["cyphercoderr/stacksync-assesment"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/cyphercoderr/StackSync-Assesment","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyphercoderr%2FStackSync-Assesment","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyphercoderr%2FStackSync-Assesment/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyphercoderr%2FStackSync-Assesment/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyphercoderr%2FStackSync-Assesment/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cyphercoderr","download_url":"https://codeload.github.com/cyphercoderr/StackSync-Assesment/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyphercoderr%2FStackSync-Assesment/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278526223,"owners_count":26001327,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-05T02:00:06.059Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","flask","flask-application","nsjail","python"],"created_at":"2025-10-05T21:58:56.060Z","updated_at":"2025-10-05T21:58:58.981Z","avatar_url":"https://github.com/cyphercoderr.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"````markdown\n# Python Script Execution Service\n\n## Overview\n\nThis project provides a **secure API service** that allows clients to submit arbitrary Python scripts and receive the result of the `main()` function execution.  \nIt is designed to meet the following business requirements:\n\n- Expose a simple **Flask API** (`/execute`) for submitting scripts.\n- Ensure **input validation** (only valid scripts with a `main()` function are accepted).\n- **Isolate execution** using [`nsjail`](https://nsjail.dev/) to protect against malicious code.\n- Support commonly needed libraries (`os`, `numpy`, `pandas`).\n- Provide **modular, production-ready code**, easily deployable on **Google Cloud Run**.\n- Return results in a structured JSON response:\n  ```json\n  {\n    \"result\": {...},   // JSON returned by main()\n    \"stdout\": \"...\",   // Print output from script execution\n    \"error\": null      // Or error details if failed\n  }\n````\n\n---\n\n## Architecture\n\n```bash\n                +--------------------+\n                |    Client (User)   |\n                +--------------------+\n                         |\n                         v\n              POST /execute { \"script\": \"...\" }\n                         |\n         +---------------+---------------+\n         |                               |\n         v                               v\n+-------------------+          +--------------------+\n|   Flask API (8080)|  -----\u003e  |  Sandbox Runner    |\n|   - Validation    |          |  (nsjail + Python) |\n|   - Controller    |          |  - Executes script |\n|                   |          |  - Captures stdout |\n+-------------------+          +--------------------+\n```\n\n### **API Service (Flask)**\n\n* Handles `/health` and `/execute` endpoints.\n* Validates scripts (syntax, presence of `main()`, disallowed imports).\n* Delegates execution to the sandbox.\n\n### **Sandbox Runner (nsjail)**\n\n* Executes script safely in an isolated environment.\n* Restricts CPU, memory, and networking.\n* Ensures malicious scripts cannot escape.\n\n---\n\n## How to Run\n\n### 1. Run Locally (Flask Dev Server)\n\nInstall dependencies:\n\n```bash\npip install -r requirements.txt\n```\n\nRun the API using Flask:\n\n```bash\nexport FLASK_APP=sandbox.runner:app\nflask run --host=0.0.0.0 --port=8080\n```\n\nAPI available at → [http://localhost:8080](http://localhost:8080)\n\n---\n\n### 2. Run Locally (Gunicorn, Production-style)\n\n```bash\ngunicorn -w 2 -b 0.0.0.0:8080 sandbox.runner:app\n```\n\n---\n\n### 3. Run with Docker\n\n**Build \u0026 Start Service**\n\n```bash\ndocker build -t sandbox-runner .\ndocker run -p 8080:8080 sandbox-runner\n```\n\n---\n\n### 4. Deploy to Google Cloud Run\n\n```bash\ngcloud run deploy sandbox-api \\\n  --source . \\\n  --platform managed \\\n  --region us-central1 \\\n  --allow-unauthenticated\n```\n\nExample request after deployment:\n\n```bash\ncurl -X POST https://\u003cYOUR-CLOUD-RUN-URL\u003e/execute \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"script\": \"def main():\\n    return {\\\"msg\\\": \\\"Hello from Cloud Run\\\"}\"}'\n```\n\n---\n\n##  Example Usage\n\n### Health Check\n\n```bash\ncurl -X GET http://localhost:8080/health\n```\n\n### Execute Script\n\n```bash\ncurl -X POST http://localhost:8080/execute \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"script\": \"def main():\\n    print(\\\"hello from sandbox\\\")\\n    return {\\\"message\\\": \\\"success\\\"}\"\n  }'\n```\n\n### Expected Response\n\n```json\n{\n  \"result\": { \"message\": \"success\" },\n  \"stdout\": \"hello from sandbox\",\n  \"error\": null\n}\n```\n\n---\n\n##  Testing\n\nUnit tests are included under `tests/` and cover:\n\n* **Validation tests**\n\n  * Missing `main()` function → should return error.\n  * Use of `eval`/`exec` → should be rejected.\n  * Oversized scripts (\u003e200KB) → should be rejected.\n\n* **Execution tests**\n\n  * `main()` returns JSON → valid result.\n  * `main()` raises exception → error returned.\n  * Script prints to stdout → output captured.\n\nRun tests with:\n\n```bash\npytest -v\n```\n\n---\n\n## ⚡ Edge Cases Considered\n\n* **No `main()` function**\n\n  ```python\n  def foo(): return {\"x\": 1}\n  ```\n\n  → Error: `script must define main()`\n\n* **Invalid JSON return**\n\n  ```python\n  def main(): return set([1, 2])\n  ```\n\n  → Error: `\"Returned value is not valid JSON\"`\n\n* **Malicious code attempt**\n\n  ```python\n  import os\n  def main(): os.system(\"rm -rf /\")\n  ```\n\n  → Blocked by validation \u0026 nsjail\n\n* **Infinite loop**\n\n  ```python\n  def main():\n      while True: pass\n  ```\n\n  → Terminated by nsjail timeout\n\n* **Large script size (\u003e200KB)**\n  → Rejected at validation step\n\n---\n\n## Development Notes\n\n* **Modular code** → API logic, validation, and sandbox execution are decoupled.\n* **Sandbox isolation** → nsjail ensures execution is safe even if validation is bypassed.\n* **Production-ready** → Small Docker image, `docker run` startup, and Cloud Run compatible.\n* **Benchmark time** → Approx. 5–6 hours including design, coding, testing, and documentation.\n\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyphercoderr%2Fstacksync-assesment","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcyphercoderr%2Fstacksync-assesment","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyphercoderr%2Fstacksync-assesment/lists"}