README

As a validator

How does the validation 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 the validator

Spaze\SecurityTxt\Check\SecurityTxtCheckHost::check() is probably what you'd want to use as it provides the most 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<SecurityTxtSpecViolation> 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<SecurityTxtSpecViolation> 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<int, list<SecurityTxtSpecViolation>> 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<int, list<SecurityTxtSpecViolation>> 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<SecurityTxtSpecViolation>, 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<SecurityTxtSpecViolation>, 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\SecurityTxtJson::createCheckHostResultFromJsonValues().

Exceptions can be recreated with Spaze\SecurityTxt\Check\SecurityTxtJson::createFetcherExceptionFromJsonValues().

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.

As a writer

You can create a security.txt file programmatically:

Create a SecurityTxt object
Add what's needed
Pass it to SecurityTxtWriter::write() it will return the security.txt contents as a string

Signing the file is not (yet) supported.

Value validation

By default, values are validated when set, and an exception is thrown when they're invalid. You can set validation level in the SecurityTxt constructor using the SecurityTxtValidationLevel enum:

NoInvalidValues (an exception will be thrown, and the value won't be set, this is the default setting)
AllowInvalidValues (an exception will be thrown but the value will still be set)
AllowInvalidValuesSilently (an exception will not be thrown, and the value will be set)

You can use the following SecurityTxt constants to serve the file with correct HTTP content type:

SecurityTxt::CONTENT_TYPE_HEADER, the value to be sent as Content-Type header value (text/plain; charset=utf-8);
SecurityTxt::CONTENT_TYPE, the correct content type text/plain
SecurityTxt::CHARSET, the correct charset as charset=utf-8

Example

$securityTxt = new SecurityTxt();
$securityTxt->addContact(new SecurityTxtContact('https://contact.example'));
$securityTxt->addContact(SecurityTxtContact::phone('123456'));
$securityTxt->addContact(SecurityTxtContact::email('email@com.example'));
$securityTxt->addAcknowledgments(new SecurityTxtAcknowledgments('https://ack1.example'));
$securityTxt->setExpires(new SecurityTxtExpires(new DateTimeImmutable('+3 months midnight')));
$securityTxt->addAcknowledgments(new SecurityTxtAcknowledgments('ftp://ack2.example'));
$securityTxt->setPreferredLanguages(new SecurityTxtPreferredLanguages(['en', 'cs-CZ']));
header('Content-Type: ' . SecurityTxt::CONTENT_TYPE_HEADER);
echo new SecurityTxtWriter()->write($securityTxt);

Exceptions

The messages in the exceptions as thrown by this library do not contain any sensitive information and are safe to display to the user using the getMessage() method. But please be aware that the messages contain server-supplied information, so please do not display the messages as HTML or do not feed them into a Markdown parser or similar. If you'd do that, a malicious server could inject content that would result in Cross-Site Scripting attack for example.

Formatting messages

If you'd like to format some of the values contained in the messages, you can use the exception's getMessageFormat() and getMessageValues() methods. The getMessageFormat() method will return an error message with %s placeholders, while getMessageValues() will return the values, including the server-supplied ones, which you can, after a proper sanitization and/or escaping, wrap in <code> tags for example, and use them to replace the placeholders.

The same goes for formatting SecurityTxtSpecViolation object messages: you can use getMessageFormat() and getMessageValues(), and also getHowToFixFormat() and getHowToFixValues().

spaze / security-txt

Maintainers

Details