# package-obfuscator
## Disclaimer
This package was developed as part of the [SocialNetworkHarvester](https://socialnetworkharvester.de/) by the Freezingdata GmbH. We found the obfuscation of packages to be essential for our work so we developed this package. The package will be maintained as long as we need the functionality for our own software. We do not and cannot guarantee long-term maintenance, nor can be guarantee support in issues. We will nevertheless try to answer all incoming questions in a timely manner. If you want to contribute feel free to create a merge request and open an issue discussing a potential bug or feature. You are free to use this software in any personal or commercial project.
## Quick-Start
To install the package-obfuscator run the following command:
```
pip install package-obfuscator
```
To use the package-obfuscator either use the cli...
```
package-obfuscate my_secret_package
```
or use the package-obfuscator in a script:
```python
import os
import package_obfuscator
current_folder = os.path.dirname(os.path.realpath(__file__))
package_folder = os.path.join(current_folder, 'my_secret_package')
package_obfuscator.obfuscate(package_folder)
```
## CLI
The CLI provides the following options
| Argument | Description | Default |
| :------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -----------------: |
| `package_location` (positional) | An absolute or relative path to the package that should be obfuscated | required |
| `--output` / `-o` | An absolute or relative path to a folder in which to place the obfuscated package content. If this argument is not provided the obfuscation will take place in the originally provided `package_location`. | `package_location` |
| `--force-overwrite` / `-f` | If the output folder is existent the obfuscator will exit. You can disable this behaviour and achieve an hard overwrite if you add this option | |
## Python API
### `package_obfuscator`
`package_obfuscator.obfuscate(package_dir, [output=..., [force_output_overwrite=False]])`
| Argument | Description | Required / Optional |
| :----------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------ |
| `package_dir` | The absolute or relative path to the package directory. | Required |
| `output` | The absolute or relative path to the directory in which to place the obfuscated files. If not provided the obfuscation will take place within the `package_dir`. | Optional |
| `force_output_overwrite` | If the output folder exists when running the code the obfuscator will exit with an exception. If you want to force an overwrite you should provide this argument with `True`. | Optional |
## When to use the `package-obfuscator`
The `package-obfuscator` should be used prior to releasing your python package in any way. The easiest way is to use the following code structure. Let's assume you are developing a module called `my_module`. Your directory structure will look something like this:
```
my-module-repository
> my_module_source
> sub_module
script2.py
__init__.py
script1.py
setup.py
```
Then it is suggested to use the `package-obfuscator` as a package in the `setup.py`.
```python
import package_obfuscator
package_obfuscator.obfuscate('my_module_source', output='my_module')
setup(
name='my_module',
version='0.0.1',
packages=find_packages(include=['my_module', 'my_module.*'])
)
```
Your wheel will then only include obfuscated code.
## How does the obfuscation work?
The obfuscation works by compiling the code within each package-related python file into binary code. It will find all python files (`*.py`) recursively and ignore all other files. The binary code is then saved into separate files. The original file will execute the binary file using the `exec` command and the `marshal` library.
## How safe is the obfuscation method?
It is important to note that the obfuscation is not completely secure. It is possible to reverse-engineer your code using the binary files. But even when converting the code back only excerpts of the code will be humanly readable straight away. This method of obfuscation is recommended for code that is not mission-critical but should nevertheless not be deployed as human-readable code.
## Test
```
docker build --rm -t test .
```
```
docker run --rm -t -v $(pwd):/root/${PWD##*/} test bash test.sh
```
Raw data
{
"_id": null,
"home_page": "https://github.com/bubblegumsoldier/package-obfuscator",
"name": "package-obfuscator",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "obfuscator",
"author": "Henry M\u00fcssemann",
"author_email": "hm@hm-dev-consulting.de",
"download_url": "https://files.pythonhosted.org/packages/d3/81/d286b8f3a1adefc4e200fbb6813b985d7161475a68244de3fe5a05b62a88/package_obfuscator-1.0.0.tar.gz",
"platform": null,
"description": "# package-obfuscator\n\n## Disclaimer\n\nThis package was developed as part of the [SocialNetworkHarvester](https://socialnetworkharvester.de/) by the Freezingdata GmbH. We found the obfuscation of packages to be essential for our work so we developed this package. The package will be maintained as long as we need the functionality for our own software. We do not and cannot guarantee long-term maintenance, nor can be guarantee support in issues. We will nevertheless try to answer all incoming questions in a timely manner. If you want to contribute feel free to create a merge request and open an issue discussing a potential bug or feature. You are free to use this software in any personal or commercial project.\n\n## Quick-Start\n\nTo install the package-obfuscator run the following command:\n\n```\npip install package-obfuscator\n```\n\nTo use the package-obfuscator either use the cli...\n\n```\npackage-obfuscate my_secret_package\n```\n\nor use the package-obfuscator in a script:\n\n```python\nimport os\nimport package_obfuscator\n\ncurrent_folder = os.path.dirname(os.path.realpath(__file__))\npackage_folder = os.path.join(current_folder, 'my_secret_package')\n\npackage_obfuscator.obfuscate(package_folder)\n```\n\n## CLI\n\nThe CLI provides the following options\n\n| Argument | Description | Default |\n| :------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -----------------: |\n| `package_location` (positional) | An absolute or relative path to the package that should be obfuscated | required |\n| `--output` / `-o` | An absolute or relative path to a folder in which to place the obfuscated package content. If this argument is not provided the obfuscation will take place in the originally provided `package_location`. | `package_location` |\n| `--force-overwrite` / `-f` | If the output folder is existent the obfuscator will exit. You can disable this behaviour and achieve an hard overwrite if you add this option | |\n\n## Python API\n\n### `package_obfuscator`\n\n`package_obfuscator.obfuscate(package_dir, [output=..., [force_output_overwrite=False]])`\n\n| Argument | Description | Required / Optional |\n| :----------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------ |\n| `package_dir` | The absolute or relative path to the package directory. | Required |\n| `output` | The absolute or relative path to the directory in which to place the obfuscated files. If not provided the obfuscation will take place within the `package_dir`. | Optional |\n| `force_output_overwrite` | If the output folder exists when running the code the obfuscator will exit with an exception. If you want to force an overwrite you should provide this argument with `True`. | Optional |\n\n## When to use the `package-obfuscator`\n\nThe `package-obfuscator` should be used prior to releasing your python package in any way. The easiest way is to use the following code structure. Let's assume you are developing a module called `my_module`. Your directory structure will look something like this:\n\n```\nmy-module-repository\n > my_module_source\n > sub_module\n script2.py\n __init__.py\n script1.py\n setup.py\n```\n\nThen it is suggested to use the `package-obfuscator` as a package in the `setup.py`.\n\n```python\nimport package_obfuscator\npackage_obfuscator.obfuscate('my_module_source', output='my_module')\n\nsetup(\n name='my_module',\n version='0.0.1',\n packages=find_packages(include=['my_module', 'my_module.*'])\n)\n```\n\nYour wheel will then only include obfuscated code.\n\n## How does the obfuscation work?\n\nThe obfuscation works by compiling the code within each package-related python file into binary code. It will find all python files (`*.py`) recursively and ignore all other files. The binary code is then saved into separate files. The original file will execute the binary file using the `exec` command and the `marshal` library.\n\n## How safe is the obfuscation method?\n\nIt is important to note that the obfuscation is not completely secure. It is possible to reverse-engineer your code using the binary files. But even when converting the code back only excerpts of the code will be humanly readable straight away. This method of obfuscation is recommended for code that is not mission-critical but should nevertheless not be deployed as human-readable code.\n\n## Test\n```\ndocker build --rm -t test .\n```\n```\ndocker run --rm -t -v $(pwd):/root/${PWD##*/} test bash test.sh\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An obfuscator for python packages.",
"version": "1.0.0",
"project_urls": {
"Download": "https://github.com/bubblegumsoldier/package-obfuscator/tarball/1.0.0",
"Homepage": "https://github.com/bubblegumsoldier/package-obfuscator"
},
"split_keywords": [
"obfuscator"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fe8188657c74d61e9cddd4a6798f5c24db168387ae799a959cfb005b5ed0574a",
"md5": "568e4ad77daac3823b20844c2a7e6486",
"sha256": "a4107a91235ae4ee5dde4e80108055c651b35d91a7974c7454149c505c57aea6"
},
"downloads": -1,
"filename": "package_obfuscator-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "568e4ad77daac3823b20844c2a7e6486",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 8330,
"upload_time": "2024-05-07T08:40:44",
"upload_time_iso_8601": "2024-05-07T08:40:44.499302Z",
"url": "https://files.pythonhosted.org/packages/fe/81/88657c74d61e9cddd4a6798f5c24db168387ae799a959cfb005b5ed0574a/package_obfuscator-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d381d286b8f3a1adefc4e200fbb6813b985d7161475a68244de3fe5a05b62a88",
"md5": "8d9c24395a33ae53f8a8c355585a4bc1",
"sha256": "3a1283f4e639813ab88bab7bda8ea08e276db648aeffc119e5df35180df58a5b"
},
"downloads": -1,
"filename": "package_obfuscator-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "8d9c24395a33ae53f8a8c355585a4bc1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 6315,
"upload_time": "2024-05-07T08:40:45",
"upload_time_iso_8601": "2024-05-07T08:40:45.501601Z",
"url": "https://files.pythonhosted.org/packages/d3/81/d286b8f3a1adefc4e200fbb6813b985d7161475a68244de3fe5a05b62a88/package_obfuscator-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-07 08:40:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bubblegumsoldier",
"github_project": "package-obfuscator",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "package-obfuscator"
}
JSON
