Reading a plugin readme for red flags is the cheapest security review you will ever do, and readme risk signals are worth checking before you install anything. Treat the document as evidence about the code, not as a promise from the author.
A README is evidence, not a brochure
A README is written before you run a single line of code, and it is free to read. That makes it the cheapest security document you will touch. The trick is to stop reading it as marketing. Every sentence about what the plugin does, what it needs, and how it updates is a small piece of evidence about the people behind it. A careful README usually means a careful project. A careless one does not prove danger, but it does lower the bar for trusting the code.
Permissions and network access
Start with what the plugin asks for. If the README lists the permissions or the network endpoints it touches, and explains why each one is needed, that is a good sign. If it asks for broad access and says nothing about it, that is a gap. The question is not only what it requests, but whether the author bothered to justify it. A plugin that reads your files should say which files and for what.
Install, secrets, and what the docs leave out
The install section is where the riskiest habits show up. Watch for a few patterns that turn a normal setup into a blind trust.
- Piping a remote script straight into a shell, the curl | sh pattern, which runs code you have not read.
- Downloading an unsigned binary with no way to check what it is.
- No mention of a pinned version, so you get whatever the server sends today.
- An update mechanism that can pull new code later without your review.
Then read how the plugin handles your data and its own code. Several omissions are worth noting before you install.
- Examples that encourage pasting tokens or env secrets into config files in plain text.
- A build step that runs arbitrary code at install time, not just at development.
- Telemetry or analytics that is never disclosed in the docs.
- No stated licence, so you do not know your rights to the code.
A table of signals and how much to worry
| Signal | What it usually means | How much to worry |
|---|---|---|
| curl | sh in install | Code runs before you read it | High |
| No pinned version | You get unreviewed updates | Medium |
| Undisclosed telemetry | Your usage is tracked silently | Medium |
| Dead links, years stale | Project likely abandoned | High for maintenance |
| Clear scopes and changelog | Maintainer thinks about risk | Low |
Sloppiness versus malice
The most useful judgement is separating the two. Most bad READMEs are simply careless. A missing changelog is not proof of malice. A dead link is annoying, not evil. Malice shows up as patterns that hide what the code does: suppressed details about network access, install steps that dodge review, updates that arrive without a look. Learn to tell a thin README from a dishonest one, because reacting to every gap the same way wastes your attention.
A careless README is a maintenance risk. A README that hides how the code runs is a trust risk. The second one is the one to walk away from.
What a good README looks like
After the warnings, it helps to know the shape of a healthy document. A good one states exactly what the plugin can and cannot do.
- Explicit permission scopes, with a reason for each.
- A changelog that shows what changed and when.
- A documented threat model, even a short one.
- Signed releases so you can verify what you downloaded.
A workflow you can actually run
None of this needs to take long. The score on our homepage / gives you a first read, and the dimensions behind it are explained in /blog/dsh-quality-score-decoded, but the README is where you confirm it. Keep the vendor out of the scoring: an independent number, like the one in /blog/why-independent-plugin-scoring, is the only kind worth trusting.
- Read the README and note anything unexplained.
- Check the independent score before you trust it.
- Pin the exact version you reviewed.
- Install in a sandbox or a throwaway environment first.
Should I refuse any plugin that uses curl | sh?
Not always, but you should read the script first. If you cannot read it, do not pipe it. Download it, inspect it, then run it yourself. The pattern is a risk because it skips that step by default.
Does an old README mean the plugin is unsafe?
Not by itself. An abandoned README means the project may be unmaintained, which is a different problem from malicious code. Check the last release date and whether the links still work before you decide.
Where does the score fit into this?
The README is your confirmation step. The score is the fast filter. Use the score to rank what you review, then let the README tell you whether the vendor's own words match the code they ship. The two together beat either alone.