Skip to content

PAL In‐depth

Jump to bottom
Katyatu edited this page Apr 19, 2024 · 18 revisions

Note

Updated as of PAL v1.1

Scripts

PAL-advprot.sh

The Advanced Protection script handles the additional methods of bolstering PAL's security efforts.

More info...

There are 3 additional means of enhancing security the user can opt-into using:

  1. Separate decryption key from share URL
  2. Add a random offset to all instance wait times
  3. Change the decryption key for an instance's folder

Separate decryption key from share URL

By default, MEGA share URLs come in the format of: https://mega.nz/folder/{share uuid}#{decryption key}

With the decryption key included in the URL, the URL is a direct access link. Meaning, a web scraping bot can automatically find the URL, access it, and download all of the contents within, without human intervention.

You can add an additional layer of protection against bots by removing the decryption key from the URL, and manually post the key some place else. By doing so, the link will lead to a MEGA page requesting the decryption key in order to gain access, thus requiring human intervention.

The MEGA share URL would look like this with the decryption key separate: https://mega.nz/folder/{share uuid}

Then all you have to do is include the {decryption key} in, for example, a Discord post right above PAL's assigned webhook bot post.

By enabling this setting, PAL's registered instances will no longer include the {decryption key} in its webhook bot posts. You will be responsible for making sure your legitimate customers have easy access to it.

Add a random (-15 ≤ x ≤ +15) minute offset to all instance wait periods

In theory, it is possible for someone to figure out how long you set your PAL instances to wait before refreshing the share URL, as the wait time you specified is a fixed number. Once someone figures it out, it is possible they could sync up their web scraping bot with your instance's refresh period, dampening your security efforts.

This can easily be fixed by incorporating a random offset that either increases or decreases the final time your instances wait before looping. By enabling this setting, a random number (0-900) is chosen, and is either added on to or subtracted from the final wait time. This results in a random (-15 ≤ x ≤ +15) minute offset which randomly changes every time an instance loops, and is different for each running instance.

Change the decryption key for an instance's folder

When you create/upload a new file/folder, MEGA generates a unique decryption key to be used by anyone who wants to access it. If you were wanting MEGA to generate a new decryption key, you would need to delete the file/folder, and re-creating/upload it.

If you wanted to change the decryption key for one of the folders assigned to one of your PAL instances, you could do so in a very easy way via the following method:

  1. Rename the current folder to {original name}-old.
  2. Create a new folder with the {original name}.
  3. Move all the files from within the old folder into the new folder.
  4. Delete the old folder.

By doing this, your instance managed share URLs will now have a new {decryption key} in its URL. If you have enabled the "Separate decryption key from share URL" setting, be sure to update your post that has the key with the new key, otherwise your customers will complain about not having access.

Note: Realistically, the way PAL operates renders this function not all that useful. However, if you did manage to catch and ban someone who was leaking your URLs, it wouldn't hurt to refresh the decryption key as it more than likely is floating around in public.

PAL-create.sh

The Instance Creation script guides the user through the process of creating an instance that PAL will run on.

More info...

All instanced are saved to ~/.config/PAL/instances.

There are 4 steps to the process of creating an instance:

  1. Choosing a name for the instance
  2. Selecting the MEGA folder on your account the instance will manage the share link for
  3. Picking the number of hours the instance will wait before rotating the share link
  4. Assigning the respective Discord webhook bot that PAL will use to publicly display the current share link

Choosing a name for the instance

Valid names consist all of the following:

  1. Exclusively alphanumeric (a-z,A-Z,0-9)
  2. Must be a name that isn't already used by an existing instance
  3. Must be of reasonable length (ie. not going over the character limit)

Selecting the MEGA folder on your account the instance will manage the share link for

Valid MEGA paths are essentially everything but the root of the cloud drive. If the path you choose doesn't exist, it will be created for you.

The use of spaces might confuse MEGAcmd, instead use underscores (_), or use pascal/camel casing.

Only use (/) when you want to pick a folder inside of a folder.

Picking the number of hours the instance will wait before rotating the share link

The input here must be an integer greater than or equal to 1 (1,2,3,4,...).

There is a hard cap of 100 for error handling reasons. Anything greater than a few hours renders PAL pointless, but if the user wishes to wait that long for whatever reason, by all means.

Assigning the respective Discord webhook bot that PAL will use to publicly display the current share link

A valid Discord webhook bot is required in order for PAL to actually deliver on its goal. The process here follows as such:

  1. The user pastes in the copied webhook bot URL from their Discord client.
  2. PAL uses that URL to POST a message through the Discord API, containing a randomly generated code. This serves as both a Discord webhook validity check and as a webhook ownership confirmation. If the API returns a bad message, a new URL is requested.
  3. If the user enters in a code that matches the internally generated code, the provided URL is confirmed. Otherwise, this step starts over.

PAL-delete.sh

The Instance Deletion script handles deleting registered instances at the user's discretion.

More info...

The process here is straightforward:

  1. PAL looks inside of ~/.config/PAL/instances, and displays all instance names to the user (if none exist, the script ends).
  2. The user picks a name from the list (non-matching names will repeat this step, 'q' ends the script).
  3. PAL offers a confirmation of deletion.
  4. If approved, PAL deletes the registered instance, and loops back to step 1. If not approved, back to step 1.

PAL-init.sh

The Initialization script is what (re)boots PAL and launches all registered instances.

More info...

This script handles the starting of internal logging, ensuring MEGA is ready, and starting every registered instance it finds. All temporary files/logs are placed inside of /tmp/PAL.

For each registered instance it starts, the output is saved to a /tmp/PAL log, and its PID is saved to /tmp/PAL/PIDs.

This script is what is called by the PAL-autostart.service on boot, and by PAL-manager if the user requests a manual PAL reboot.

PAL-installer.sh

The Installer script handles setting up PAL's folder hierarchy, downloading the latest version, moving files where they need to go, and setting up auto start services.

More info...

The process follows as such:

  1. Check if PAL is already installed, continue if not found.
  2. Check if required dependencies are installed, continue if they are.
  3. Explain to the user what will be installed and where everything will go, continue if user approves.
  4. Go though the process of installing PAL:
    1. Create the PAL home directory ~/.config/PAL
    2. Fetch the latest release from this repo and extract it inside of PAL's home
    3. Create the folder hierarchy within PAL's home
    4. Move all of the control scripts into ./control
    5. Move PAL-manager into ~/bin/
    6. Move the services into ~/.config/systemd/user
    7. Tell systemd to enable the moved services

PAL-instance.sh

The Instance script is essentially what PAL is. With parameters given by the init script, this script handles the routine deleting/generating share links and deleting/posting them through the webhook bot.

More info...

Each PAL-instance is started with parameters passed by PAL-init, who read in the configuration of all registered instances created by PAL-create. Once loaded, the instance loop runs as such:

  1. Using MEGAcmd, if the assigned MEGA folder has an existing share link, delete it.
  2. Using the assigned Discord webhook bot, if the webhook bot was previously ran, re-use the saved Discord messageID (found in ./instances/messageIDs). If there was a saved messageID, but the message no longer exists, create a new message (Discord API POST call) and save that messageID. Otherwise, create a new message (Discord API POST call) and save that messageID.
  3. If the user has enabled the 'Random Interval' advanced protection setting, generate the random number and save it.
  4. Using MEGAcmd, create a new MEGA share link for the instance assigned folder and save the returned URL.
  5. Extract the base share URL and decryption key from the returned URL.
  6. Using the assigned Discord webhook bot, make a PATCH call to the Discord API, pointing to the messageID saved earlier, with the message content being the new share link. If the user has enabled the 'Separate Key' advanced protection setting, exclude the decryption key from the message.
  7. Print to the console all the information saved/generated from the loop.
  8. Sleep for the assigned amount of time (+ the 'Random Interval' offset, if enabled).
  9. Go to step 1.

PAL-kill.sh

The Kill script handles the termination of all running instances and de-inits PAL.

More info...

Pretty self-explanatory. This script looks inside of /tmp/PAL/PIDs, reads off every filename, and performs a SIGTERM on each PID. Afterwards, /tmp/PAL is deleted and PAL is marked as offline. To start PAL again, either re-init with PAL-manager or reboot the system.

PAL-log.sh

The Log script gives the user easy access to the logs of each running instance.

More info...

This script looks inside of /tmp/PAL for any instance logs, displays the available logs to the user, and displays the log the user chooses.

Here you will be able to find the instance's:

  1. Current share URL
  2. Current share URL's decryption key
  3. Current share URL expiration timestamp (ie. when the instance loops)
  4. Targeted Discord messageID the instance uses to deliver the share URL

Until PAL is rebooted, these logs will retain the information of all prior iterations.

PAL-manager.sh

The Manager script is the central control hub for PAL. All other scripts are called through this script.

More info...

PAL-manager checks to make sure you are logged into MEGAcmd before allowing any further action. It will also give you the status of PAL, whether its online or offline.

The available control options are as follows:

  • Create an instance (PAL-create)
  • Delete an instance (PAL-delete)
  • Advanced Protection (PAL-advprot)
  • Re-initialize PAL (PAL-init)
  • De-initialize PAL (PAL-kill)
  • View an instance's log (PAL-log)
  • Check for PAL update (PAL-update)
  • Uninstall PAL (PAL-uninstaller)

Refer to each corresponding (PAL-*)'s section for further information.

PAL-uninstaller.sh

The Uninstaller script handles the complete removal of PAL by essentially undoing everything the installer script did.

More info...

The process follows as such:

  1. Check if PAL is installed, continue if found.
  2. Explain to the user what will be removed, continue if user approves.
  3. Go though the process of uninstalling PAL:
    1. Tell systemd to disable the services that were installed
    2. Remove the services from ~/.config/systemd/user
    3. Remove PAL-manager from ~/bin/
    4. Delete the PAL home directory ~/.config/PAL

PAL-update.sh

The Update script upgrades the local PAL installation via uninstall old version/install new version all while preserving existing instances.

More info...

The process follows as such:

  1. Fetch the latest version number from this repo, continue if higher than the installed PAL's version
  2. Copy all registered instances to ~/PAL-{randomint}
  3. Call PAL-uninstaller, continue if uninstall is successful
  4. Fetch and run the latest installer script from this repo, continue if install is successful
  5. Move all ~/PAL-{randomint} instances back into PAL's saved instances folder

Services

MEGAcmd-autostart.service

The MEGAcmd-autostart service is a helper service that ensures the MEGAcmd server is kept online for PAL to quickly access.

More info...

[Unit]
Description=Autostart the MEGAcmd server
Requires=network-online.target
After=network-online.target # Wait for internet access

[Service]
Type=simple
ExecStart=/usr/bin/mega-cmd-server
Restart=always # Keep the MEGAcmd server running

[Install]
WantedBy=default.target

PAL-autostart.service

The PAL-autostart service triggers the init script once the system is booted, connected to the internet, and MEGAcmd is online.

More info...

[Unit]
Description=Autostart all registered PAL instances
Requires=MEGAcmd-autostart.service
After=MEGAcmd-autostart.service # Wait for the MEGAcmd server

[Service]
Type=oneshot # Run PAL-init once
ExecStart=/usr/bin/bash -c 'exec $HOME/.config/PAL/control/PAL-init.sh'
KillMode=process # Keeps instances running after PAL-init completes and exits

[Install]
WantedBy=default.target

Clone this wiki locally