{"id":27629344,"url":"https://github.com/bimalpaudels/restricted","last_synced_at":"2025-04-23T15:16:29.897Z","repository":{"id":289333175,"uuid":"970832974","full_name":"bimalpaudels/restricted","owner":"bimalpaudels","description":"A lightweight Python package for analyzing and securely executing code blocks with AST-based restrictions.","archived":false,"fork":false,"pushed_at":"2025-04-23T07:54:31.000Z","size":33,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-23T15:16:24.829Z","etag":null,"topics":["ast","exec","interpreter","python","restricted","uv"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bimalpaudels.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}},"created_at":"2025-04-22T15:50:24.000Z","updated_at":"2025-04-23T07:54:07.000Z","dependencies_parsed_at":"2025-04-22T19:17:26.285Z","dependency_job_id":null,"html_url":"https://github.com/bimalpaudels/restricted","commit_stats":null,"previous_names":["bimalpaudels/restricted"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bimalpaudels%2Frestricted","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bimalpaudels%2Frestricted/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bimalpaudels%2Frestricted/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bimalpaudels%2Frestricted/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bimalpaudels","download_url":"https://codeload.github.com/bimalpaudels/restricted/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250457784,"owners_count":21433734,"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","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":["ast","exec","interpreter","python","restricted","uv"],"created_at":"2025-04-23T15:16:29.469Z","updated_at":"2025-04-23T15:16:29.889Z","avatar_url":"https://github.com/bimalpaudels.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"### restricted: Enforcing Restrictions on Python Code Execution\n\n## Overview\nA Python code execution environment with support for restricting imports, built-ins with AST-based validation. This package provides multiple execution methods, including subprocesses and `uv`, allowing for controlled execution with customizable restrictions on potentially unsafe code.\n\n\n## Installation\n\n### pip\n```text\npip install restricted\n```\n### uv\n```text\nuv add restricted\n```\n\n## Usage\n### With helper function\nThe helper function could be used to execute code block the easiest with uv. \n```python\nfrom restricted.helpers import execute_restricted\n\n# A block of code pretending to be malicious.\ncode=\"\"\"\nimport os\nprint(os.getcwd())\n\"\"\"\n\nprint(execute_restricted(code))\n\n# Shell Output\nImportError: 'os' is not allowed\n```\n\n#### Custom restrictions\nYou can provide your own restricting modules and built-in functions to restrict.\n```python\nfrom restricted.helpers import execute_restricted\n...\ncustom_restricted_modules = [\"os\", \"sys\", \"asyncio\", 'builtins'] \ncustom_restricted_builtins = [\"print\", \"open\", \"min\", \"max\"]\n\nresult = execute_restricted(code, restricted_modules=custom_restricted_modules, restricted_builtins=custom_restricted_builtins)\n```\n\n#### Execute without restriction\nDuring development, code could be tested without restrictions by passing the `restrict=False` flag to the helper function.\n```python\nfrom restricted.helpers import execute_restricted\n\n# A block of code pretending to be malicious.\ncode=\"\"\"\nimport os\nprint(os.getcwd())\n\"\"\"\n\nprint(execute_restricted(code, restrict=False))\n\n# Shell Output\nhome/foo/projects/somefolder\n```\n### Without helper function\nFor more advanced control over the execution process, you can use the Executor directly. This approach allows you to manage both the restriction and the execution method.\n```python\nfrom restricted.core import Executor, Restrictor\ncode=\"\"\"\nprint(\"Hello World\")\n\"\"\"\ncustom_restricted_modules = [\"os\", \"sys\", \"asyncio\", 'builtins'] \n\ncustom_restrictor = Restrictor(restricted_modules=custom_restricted_modules)\nexecutor = Executor(code, restrictor=custom_restrictor)\n\n# Different execution methods\nexecutor.direct_execution() or executor.subprocess_execution()\n...\n```\n### Using only the Restrictor\nIt's not necessary always use the Executor. Many use cases could need just the validation and not the execution. \nThe `Restrictor` class can be used on it's own for finer control with execution behavior.\n```python\nfrom restricted.core import Restrictor, SyntaxParser\ncode=\"\"\"\nprint(\"Hello World\")\n\"\"\"\ntree = SyntaxParser().parse_and_validate(code=code)\n\n# Only restrict certain modules\ncustom_restricted_modules = [\"os\", \"sys\", \"asyncio\", 'builtins'] \nrestrictor = Restrictor(restrict_modules=True, restrict_builtins=False, restricted_modules=custom_restricted_modules)\n\n# Only restrict certain built-ins\ncustom_restricted_builtins = [\"print\", \"open\", \"min\", \"max\"]\nrestrictor = Restrictor(restrict_modules=False, restrict_builtins=True, restricted_builtins=custom_restricted_builtins)\n\n# Visit the nodes\nrestrictor.visit(tree)\n```\n\n## Security Notice\n**Caution**: Always ensure that the code you execute is thoroughly reviewed to avoid potential security risks. Malicious or unsafe code can harm the system or access sensitive resources. Consider running code in a controlled or isolated environment to minimize potential damage.\n\n## Contribution\nAny contributions to improve this project are welcome! If you have suggestions, bug fixes, or new features to propose, \nfeel free to submit a pull request on [GitHub](https://github.com/bimalpaudels/restricted). \n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbimalpaudels%2Frestricted","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbimalpaudels%2Frestricted","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbimalpaudels%2Frestricted/lists"}