{"id":18595581,"url":"https://github.com/minapecheux/medusa","last_synced_at":"2025-11-02T05:30:33.597Z","repository":{"id":122870011,"uuid":"262655304","full_name":"MinaPecheux/Medusa","owner":"MinaPecheux","description":"A small encoding/decoding Python lib.","archived":false,"fork":false,"pushed_at":"2024-05-03T20:25:52.000Z","size":124,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-12-26T20:43:16.959Z","etag":null,"topics":["cryptography","python","utility"],"latest_commit_sha":null,"homepage":null,"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/MinaPecheux.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}},"created_at":"2020-05-09T20:41:28.000Z","updated_at":"2024-05-03T20:25:50.000Z","dependencies_parsed_at":"2024-05-03T21:52:35.378Z","dependency_job_id":null,"html_url":"https://github.com/MinaPecheux/Medusa","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MinaPecheux%2FMedusa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MinaPecheux%2FMedusa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MinaPecheux%2FMedusa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MinaPecheux%2FMedusa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MinaPecheux","download_url":"https://codeload.github.com/MinaPecheux/Medusa/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239379322,"owners_count":19628684,"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":["cryptography","python","utility"],"created_at":"2024-11-07T01:20:10.766Z","updated_at":"2025-11-02T05:30:33.555Z","avatar_url":"https://github.com/MinaPecheux.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Medusa\n\nThe Mini Encoding/Decoding Utility with Simple Algorithms (Medusa) is a small Python lib to easily cipher and decipher files or directories using basic cryptography algorithms.\n\n\u003cdiv style=\"text-align: center;\"\u003e\n\u003cimg src=\"imgs/logo.png\" alt=\"logo.png\" width=\"150\" height=\"150\" /\u003e\n\u003c/div\u003e\n\nFor now, Medusa offers 4 encoding/decoding algorithms:\n- the basic [Caesar (or shift) cipher](https://en.wikipedia.org/wiki/Caesar_cipher): a symmetric cryptography\n  method that simply shifts letters by a given offset to get a ciphertext alphabet\n- the [Vigenere cipher](https://en.wikipedia.org/wiki/Vigen%C3%A8re_cipher): a symmetric polyalphabetic cryptography\n  method that uses a key and a complement key\n- the [Advanced Encryption Standard (AES)](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard): a symmetric\n  cipher (here, it uses a key that is derived into an initial integer value)\n- the [Rivest-Shamir-Adleman (RSA)](https://en.wikipedia.org/wiki/RSA_(cryptosystem)) algorithm: an asymmetric\n  cipher with a public and a private key\n\n_Note: to make it harder to decipher, Medusa uses a wide range of characters including Unicode characters... so it requires Python 3 to work._\n\n## Install\n\nTo install Medusa, use `pip` from the online Github repository:\n\n```\npip install git+https://github.com/MinaPecheux/Medusa.git#egg=medusa\n```\n\nThis will install the Python lib and also a command-line `medusa` to run it directly in a shell.\n\n## TL;DR\n\nTo encrypt a file or a folder, use the Medusa CLI with the `-e` or `--encrypt` argument:\n\n```\nmedusa -e cli --algo vigenere -i \u003cinput_path\u003e -o \u003coutput_path\u003e\n```\n\nTo decrypt a file or a folder, use the Medusa CLI with the `-d` or `--decrypt` argument:\n\n```\nmedusa -d cli --algo vigenere -i \u003cinput_path\u003e -o \u003coutput_path\u003e\n```\n\n_Note: be careful that the Medusa CLI uses a subcommand `cli` for direct arguments passing. This is because the CLI\nalso allows for a config file-based set up (see below for more details)._\n\nThe module will automatically detect whether the input path is a file or a folder; if it is a folder, the directory will be processed recursively.\n\n## Advanced CLI usage\n\n### Autozip output\n\nIf you want process a folder and you want the processed output to be zipped automatically, simply add the `-z` or `--zip` argument!\n\n```\nmedusa -e cli -a vigenere -i \u003cinput_path\u003e -o \u003coutput_path\u003e --zip\n```\n\n### Exclude specific files or folders\n\nYou can also ignore specific files or folders by passing a list of names in the `--exclude` argument:\n\n```\nmedusa -e cli -a vigenere -i \u003cinput_path\u003e -o \u003coutput_path\u003e --exclude __pycache__ .DS_Store\n```\n\n### Verbose mode\n\nTo get more details on the process, enable the verbose logging mode with the `-v` or `--verbose` argument:\n\n```\nmedusa -e cli -a vigenere -i \u003cinput_path\u003e -o \u003coutput_path\u003e -v\n```\n\n## Configuration file\n\nIt is often easier to write all of your settings in a config file and to then simply load this file upon CLI execution.\nMedusa allows you to run the CLI with the `config` subcommand (rather than the `cli` subcommand as before):\n\n```\nmedusa (-e | -d) config \u003cconfig_file_path\u003e\n```\n\nA Medusa\nconfig file is of the following form:\n\n    [encode]\n    input = utests/data/input.txt\n    output = utests/data/output.txt\n    algo = vigenere\n    zip = true # or \"TRUE\", or \"True\"\n\n    [decode]\n    input = utests/data/output.txt\n    output = utests/data/new.txt\n    algo = vigenere\n\n_Note: You can write the `[encode]` and `[decode]` parts in whichever order you prefer, and you don't need to put spaces around the equal signs._\n\nHere are the available settings (for each `[encode]` and `[decode]` part). Some are required (they are marked with a `*` sign below) while others are optional (they have default values):\n\n| Parameter  | Description                                                              | Default    |\n|------------|--------------------------------------------------------------------------|------------|\n| `input` *  | Path to the input file or dir to process.                                |    -       |\n| `output` * | Path to the output file or dir (where to write the processed data).      |    -       |\n| `algo` *   | Algorithm to use for the encode/decode process.                          |    -       |\n| `exclude`  | List of files or folders to ignore during processing.                    | empty list |\n| `zip`      | If true, create a zip with the processed data (only for dir processing). | `false`    |\n| `verbose`  | If true, print additional logs during process.                           | `false`    |\n\n## Script usage\n\nWhen you want to use Medusa in a Python script, you can either:\n\n1. run a Medusa process with some args and then some interactive user inputs for on-the-fly keys definition\n2. or instantiate a `Medusa` object to use and reuse as much as you want\n\nThe first possibility is a nice way of putting some Medusa logic in the middle of your script. You must pass the lib some args:\n\n- the algorithm, the input path, the output path and the action to perform are required (the action can be either \"encode\" or \"decode\")\n- you may pass optional parameters (see the previous section for details on each): `zip`, `exclude` and `verbose`\n\nHere is an example script using this technique:\n\n```py\nfrom medusa import medusa\n\nif __name__ == '__main__':\n    # do some stuff...\n    print('Hello world.')\n\n    # run Medusa with some basic args\n    medusa(algo='vigenere',\n           input='../utests/data/input.txt',\n           output='../utests/data/output.txt',\n           action='encode')\n\n    # wrap up with some other thing\n    print('Goodbye world.')\n```\n\nYou can also pass a path to a configuration file, like with the CLI:\n\n```py\nfrom medusa import medusa\n\nif __name__ == '__main__':\n    # do some stuff...\n    print('Hello world.')\n\n    # run Medusa with a config file\n    medusa(config='.medusa', action='encode')\n\n    # wrap up with some other thing\n    print('Goodbye world.')\n```\n\nThe second possibility allows you to reuse the same Medusa processor for multiple tasks, like so:\n\n```py\nfrom medusa import Medusa\n\nif __name__ == '__main__':\n    processor = Medusa(algo='vigenere',\n                       params=dict(key='key',\n                                   complement_key='complement_key'))\n\n    # ENCODING\n    # encode a string directly\n    encoded = processor.encode('hello world')\n\n    # encode some file\n    processor.encode_file('../utests/data/input.txt',\n                          '../utests/data/output.txt')\n\n    # encode some directory\n    processor.encode_dir('../utests/data/input_dir',\n                         '../utests/data/output_dir')\n\n    # DECODING\n    # decode a string directly\n    decoded = processor.decode('ÓÐ×Ñè‹ÜèÝ×Ý')\n\n    # decode some file\n    processor.decode_file('../utests/data/output.txt',\n                          '../utests/data/new.txt')\n\n    # decode some directory\n    processor.decode_dir('../utests/data/output_dir',\n                         '../utests/data/new_dir')\n```\n\n_Note: whenever you use Medusa in a script, the lib will infer the path of the calling script as the base path for all input/output paths building. For example, if you save the above scripts in an `examples/` folder and then run them, all paths will be relative to this `examples/` subfolder._\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fminapecheux%2Fmedusa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fminapecheux%2Fmedusa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fminapecheux%2Fmedusa/lists"}