Skip to content

Commit 9b3d848

Browse files
committed
Add a security policy and a README section on security posture
There was no SECURITY.md, so the repository's security tab showed no policy even though private vulnerability reporting is enabled and is how reports already arrive. The policy names the reporting channel, what makes a report useful, which versions get fixes, and what falls in and out of scope. Both files state plainly that the address-property checks are one layer of an SSRF guard rather than a guard, since every advisory published against this library so far has come from that assumption. They also spell out that isValid() returning false means the string is not a valid literal of that family, not that it cannot reach an internal host: 2130706433, 0x7f000001 and 127.1 are all rejected here and all resolve to loopback. The README section records how releases are built and verified, including that provenance attestations start at 10.2.1 rather than covering every version.
1 parent e84a7b3 commit 9b3d848

3 files changed

Lines changed: 45 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -275,6 +275,14 @@ A few terms used throughout the API can be confusing if you haven't worked deepl
275275

276276
<!-- API:END -->
277277

278+
### Security
279+
280+
Vulnerabilities go through [GitHub's private vulnerability reporting](https://github.com/beaugunderson/ip-address/security/advisories/new); [SECURITY.md](./SECURITY.md) has the scope and what to expect. Confirmed issues get a fix, a release, and a public [advisory](https://github.com/beaugunderson/ip-address/security/advisories) with a CVE, rather than a quiet patch.
281+
282+
Releases are built and published by CI through npm trusted publishing. Every version from 10.2.1 onward carries a provenance attestation tying the tarball to the commit and workflow that built it. Check it with `npm audit signatures`.
283+
284+
If you are using the address-property checks as a security control, read [that section of SECURITY.md](./SECURITY.md#classifiers-are-not-an-ssrf-defense) first. `isPrivate()`, `isLoopback()`, `isInSubnet()` and their siblings classify an address that has already been parsed, which makes them one layer of an SSRF guard rather than the whole of it. A hostname that resolves to an internal address, a DNS record that changes after your check, or a redirect will all sail past a guard built only on them.
285+
278286
### Used by
279287

280288
`ip-address` is downloaded ~66 million times per week, mostly via the Node proxy/agent ecosystem. The dependency chain runs through a handful of widely-used packages:

‎SECURITY.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Security policy
2+
3+
## Reporting a vulnerability
4+
5+
Report privately through [GitHub's private vulnerability reporting](https://github.com/beaugunderson/ip-address/security/advisories/new). Please don't open a public issue for a suspected vulnerability.
6+
7+
The most useful report is a short proof of concept: the input string, the method you called, what came back, and what you expected instead. If the problem is that this library disagrees with something else about what an address means, name the other parser. A resolver, a URL implementation, another library. That is what makes the disagreement reproducible.
8+
9+
Reports are acknowledged as soon as practical. Confirmed issues get a fix, a release, and a published advisory with a CVE. Reporters are credited by GitHub handle unless they would rather not be.
10+
11+
## Supported versions
12+
13+
Fixes go out against the latest published version. There are no long-term support branches, so upgrading is the supported path.
14+
15+
## Scope
16+
17+
In scope is anything that makes this library report something untrue about an address. A validation gap. A parse result that disagrees with the resolver the address will actually be handed to. A classifier returning the wrong answer for well-formed input. A crash on input that should have been rejected cleanly.
18+
19+
Out of scope are vulnerabilities in packages that depend on this one, and reports whose only substance is that an application used these methods as its sole defense. The next section explains why.
20+
21+
## Classifiers are not an SSRF defense
22+
23+
`isPrivate()`, `isLoopback()`, `isLinkLocal()`, `isInSubnet()` and their siblings answer a question about an address that has already been parsed. That makes them one useful layer in a Server-Side Request Forgery guard. It does not make them a guard.
24+
25+
Plenty gets past them, because plenty never reaches this library at all: a hostname that resolves to an internal address, a DNS record that changes between your check and your connection, a redirect to somewhere new.
26+
27+
`isValid()` returning `false` deserves particular care. It means "not a valid literal of this family". It does not mean "will not reach an internal host". `2130706433`, `0x7f000001` and `127.1` are all rejected here, and all three resolve to loopback. A guard that treats a rejected string as safe to pass along has an opening.
28+
29+
A guard that holds up resolves the hostname itself and checks the resolved address against the socket it is about to open, on every hop. Use these methods inside that, not instead of it.

‎scripts/readme-template.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,14 @@ A few terms used throughout the API can be confusing if you haven't worked deepl
9999
<!-- API:START -->
100100
<!-- API:END -->
101101

102+
### Security
103+
104+
Vulnerabilities go through [GitHub's private vulnerability reporting](https://github.com/beaugunderson/ip-address/security/advisories/new); [SECURITY.md](./SECURITY.md) has the scope and what to expect. Confirmed issues get a fix, a release, and a public [advisory](https://github.com/beaugunderson/ip-address/security/advisories) with a CVE, rather than a quiet patch.
105+
106+
Releases are built and published by CI through npm trusted publishing. Every version from 10.2.1 onward carries a provenance attestation tying the tarball to the commit and workflow that built it. Check it with `npm audit signatures`.
107+
108+
If you are using the address-property checks as a security control, read [that section of SECURITY.md](./SECURITY.md#classifiers-are-not-an-ssrf-defense) first. `isPrivate()`, `isLoopback()`, `isInSubnet()` and their siblings classify an address that has already been parsed, which makes them one layer of an SSRF guard rather than the whole of it. A hostname that resolves to an internal address, a DNS record that changes after your check, or a redirect will all sail past a guard built only on them.
109+
102110
### Used by
103111

104112
`ip-address` is downloaded ~66 million times per week, mostly via the Node proxy/agent ecosystem. The dependency chain runs through a handful of widely-used packages:

0 commit comments

Comments
 (0)