https://github.com/spaze/security-txt
https://github.com/spaze/security-txt
Last synced: about 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/spaze/security-txt
- Owner: spaze
- License: mit
- Created: 2022-01-13T18:34:15.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-08-09T11:04:53.000Z (10 months ago)
- Last Synced: 2024-08-09T12:30:01.957Z (10 months ago)
- Language: PHP
- Size: 233 KB
- Stars: 3
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# `security.txt` validator
## How does it work
This package can validate `security.txt` file either by providing
- the file contents as a string by calling `Spaze\SecurityTxt\Parser\SecurityTxtParser::parseString()`
- a hostname like `example.com` to `Spaze\SecurityTxt\Parser\SecurityTxtParser::parseHost()`
- a URL like `https://example.com/` to `Spaze\SecurityTxt\Check\SecurityTxtCheckHost::check()`
Each of the options above will call preceding method and add more validations which are only possible in that particular case.
There's also a command line script in `bin` which uses `Spaze\SecurityTxt\Check\SecurityTxtCheckHostCli::check()` mostly just to add command line output to `Spaze\SecurityTxt\Check\SecurityTxtCheckHost::check()`.
If you want to decouple fetching the `security.txt` file and parsing it, there's also a possibility to pass a `SecurityTxtFetchResult` object to `Spaze\SecurityTxt\Parser\SecurityTxtParser::parseFetchResult()`.
## How to use it
`Spaze\SecurityTxt\Check\SecurityTxtCheckHost::check()` is probably what you'd want to use as it provides the mos comprehensive checks, can pass a URL, not just a hostname, and also supports callbacks. It accepts these parameters:
`string $url`
A URL where the file will be looked for, you can pass just for example `https://example.com`, no need to use the full path to the `security.txt` file, because only the hostname of the URL will be used for further checks
`?int $expiresWarningThreshold = null`
The validator will start throwing warnings if the file expires soon, and you can say what "soon" means by specifying the number of days here
`bool $strictMode = false`
If you enable strict mode, then the file will be considered invalid, meaning `SecurityTxtCheckHostResult::isValid()` will return `false` even when there are only warnings, with strict mode disabled, the file with only warnings would still be valid and `SecurityTxtCheckHostResult::isValid()` would return `true`
`bool $noIpv6 = false`
Because some environments do not support IPv6, looking at you GitHub Actions
`Spaze\SecurityTxt\Check\SecurityTxtCheckHost::check()` returns a `Spaze\SecurityTxt\Check\SecurityTxtCheckHostResult` object with some obvious and less obvious properties.
The less obvious ones can be obtained with the following methods. All of them return an array of `SecurityTxtSpecViolation` descendants.
### `getFetchErrors()`
Returns `list` and contains errors encountered when fetching the file from a server. For example but not limited to:
- When the content type or charset is wrong
- When the URL scheme is not HTTPS
### `getFetchWarnings()`
Also returns `list` and has warnings when fetching the file, like for example but not limited to:
- When the files at `/security.txt` and `/.well-known/security.txt` differ
- When `/security.txt` does not redirect to `/.well-known/security.txt`
### `getLineErrors()`
Returns `array>` where the array `int` key is the line number. Contains errors discovered when parsing and validating the contents of the `security.txt` file. These errors are produced by any class that implements the `FieldProcessor` interface. The errors include but are not limited to:
- When a field uses incorrect separators
- When a field value is not URL or the URL doesn't use `https://` scheme
### `getLineWarnings()`
Also returns `array>` where the array `int` key is the line number. Contains warnings generated by any class that implements the `FieldProcessor` interface, when parsing and validating the contents of the `security.txt` file. These warnings include but are not limited to:
- When the `Expires` field's value is too far into the future
### `getFileErrors()`
Returns `list`, the list contains file-level errors which cannot be paired with any single line. These error are generated by `FieldValidator` child classes, and include:
- When mandatory fields like `Contact` or `Expires` are missing
### `getFileWarnings()`
Returns `list`, the list contains file-level warnings that cannot be paired with any single line. These warnings are generated by `FieldValidator` child classes, and include for example:
- When the file is signed, but there's no `Canonical` field
## Callbacks
`SecurityTxtCheckHost::check()` supports callbacks that can be set with `SecurityTxtCheckHost::addOn*()` methods. You can use them to get the parsing information in "real time", and are used for example by the `bin/checksecuritytxt.php` script via the `\Spaze\SecurityTxt\Check\SecurityTxtCheckHostCli` class to print information as soon as it is available.
## JSON
The `Spaze\SecurityTxt\Check\SecurityTxtCheckHostResult` object can be encoded to JSON with `json_encode()`,
and decoded back with `Spaze\SecurityTxt\Check\SecurityTxtCheckHostResultFactory::createFromJson()`.
## The other methods
Both `Spaze\SecurityTxt\Parser\SecurityTxtParser::parseString()` and `Spaze\SecurityTxt\Parser\SecurityTxtParser::parseHost()` return a `Spaze\SecurityTxt\Parser\SecurityTxtParseResult` object with similar methods as what's described above for `SecurityTxtCheckHostResult`.
The result returned from `parseHost()` also contains `Spaze\SecurityTxt\Fetcher\SecurityTxtFetchResult` object.