PushWarden docs

Free and Pro

PushWarden finds the malware and stops it from running in both versions. PushWarden Pro adds the two steps that save you work afterwards: removing only the malicious part of an infected file, and fixing your GitHub repositories for you.

What each version does

  Free Pro
Scanning: repositories, this computer, scan, check-staged, CI mode Yes Yes
Real-time guard, alerts, activity history Yes Yes
Stopping malicious processes, removing persistence, firewall block, editor hardening Yes Yes
Catching the same tricks from other campaigns (generic rules) Yes Yes
Malicious files: fake fonts, auto-run tasks, propagation scripts Quarantined Quarantined
A config or entry file with malware added to it (postcss.config.mjs, .gitignore, …) The whole file is quarantined, so the malware cannot run. Your own code in that file goes with it until you restore or repair it Only the malicious part is removed. The file stays in place with your code intact
GitHub repositories: github-clean and the guided screens (pushwarden ui) Check only: shows every infected branch and what would change Check, then fix and push every infected branch
Restoring anything from quarantine Yes Yes

Everything PushWarden changes is copied to quarantine first in both versions, and pushwarden history puts it back.

Devices

A Pro key works on a limited number of devices, set when the key is issued: one computer, three, ten. The first time a computer is activated it takes one of the places. Activating the same computer again, after a reinstall for example, costs nothing. A key that is already used on all its devices is refused on a new one. The message does not say which other computers use the key.

If you need to move a key to a new computer, or free a place, contact the person you bought it from. Removing a device is done by them, not from the program.

Getting a key

Pro keys are not on sale online yet. To get one, write to [email protected]. A key looks like PW- followed by four groups of five letters and digits, and it may have an end date.

Activating Pro

pushwarden activate PW-XXXXX-XXXXX-XXXXX-XXXXX     # needs an internet connection, once
pushwarden activate                                # or run it alone and paste the key when asked

PushWarden sends the key and a description of this computer to the licence server, which answers with a licence for this computer. The command prints how many of the key’s devices are in use and what is now unlocked. The running guard picks it up straight away; there is nothing to restart.

On a server, set the key in the environment instead: the guard activates it once.

export PUSHWARDEN_LICENSE_KEY=PW-XXXXX-XXXXX-XXXXX-XXXXX

Every computer that does this uses one of the key’s places, so short-lived machines such as build runners that start from scratch each time are not a good fit for a device licence.

Checking your licence

pushwarden licence               # plan, licensed to, devices in use, when it was last confirmed
pushwarden licence --refresh     # ask the licence server now
pushwarden licence --remove      # delete the saved key from this computer
pushwarden status                # the Plan line shows the same

pushwarden license (US spelling) works too. --remove only deletes the key from this computer. The computer keeps its place on the key, and activating again here uses no further place.

How the licence is checked

  • A licence for this computer. The server’s answer is signed and names this computer. PushWarden checks that signature with a public key built into the program, so a licence.json copied to another computer does not unlock Pro there.
  • About once a day. The guard asks the server to confirm the key. If the key was revoked, has expired, or this computer was removed, Pro ends at once.
  • Offline. If the server cannot be reached, Pro keeps working for 7 days after its last answer. After that PushWarden works as the free version until it can reach the server again; pushwarden licence --refresh brings Pro back. Nothing that Pro already cleaned is undone.
  • The clock. The 7 days are counted with the computer’s clock, so PushWarden remembers the latest time the clock showed while the licence was in force. A clock that reads more than an hour earlier than that, or earlier than the licence server’s last answer, switches Pro off: turning the clock back does not add offline days. If the clock was wrong and has been corrected, pushwarden licence --refresh (or the guard’s next check) resets it from the server’s time. A clock that is simply behind has to be corrected.
  • End date. A key with an end date stops unlocking Pro after that day.
  • Free never connects. The free version makes no licence requests.

What the licence server receives

Only when you activate or the guard confirms a Pro key: the key, a hash that identifies this computer (not the operating system’s own id), the computer’s host name, the operating system and processor type, and the PushWarden version. The host name is shown to the key’s owner so a computer can be recognised when its places are used up. Nothing else leaves the computer. See Security and privacy.

Stored locally: the key and the signed licence are in licence.json in the data directory (~/.pushwarden), readable only by you.