Documentation

Documentation to build on the Passmarked platform

Occurrences

Passmarked runs tests on websites, which can be either single pages or full websites. The API can be used to start and wait for reports to run and return with the results.

These results of these tests, produce a list of issues that each have their own occurrences where these problems were found. One issue can contain up to a max of 50 returnable occurrence. Occurrences after this are simply counted to save processing.

Install

To enable the Passmarked Client side API in your project, add the following script:

<script src="//jsapi.passmarked.com/v1.js"></script>

For more details, see github.com/passmarked/js on the project itself.

After adding the script, the passmarked object will become available for use

Request

To request the ocurrences of a report, the .getOccurrences() function is provided. The function is called as such:

passmarked.getOccurrences({
  report: '(report-uid)',
  test: 'ssl', // OPTIONAL - filter by test
  uid:  'heartbleed' // OPTIONAL - filter by rule,
  offset: 0
}, function(err, occurrences) {
  if(err) {
    console.error(err);
  } else {
    for(var i = 0; i < occurrences.length; i++) {
      console.log(occurrences[i].getMessage());
      console.log(occurrences[i].getDisplay());
      console.log(occurrences[i].getChain());
      console.log(occurrences[i].getCode());
      console.log(occurrences[i].getURL());
    }
  }
});

The function supports and expects a few parameters as such:

NameTypeDescription
reportstringREQUIRED - The UID of the report to fetch the occurrences for
teststringOPTIONAL - Filter out occurrences by it's test
uidstringOPTIONAL - Filter by the rule, which allows showing occurrences for only a specific rule
offsetintegerOPTIONAL - Number of offset to use when listing the occurrences

Response

The function will return an array of Occurrence objects that has the following functions:

NameTypeDescription
.getDisplay()stringReturns the format of which how the data can be displayed. See Display Types
.getMessage(boolean)stringReturns the message of the occurrence with placeholders ($). If the .getMessage(true), the placeholders will be replaced.
.getIdentifiers()stringReturns the list of identifiers that are meant to replace the placeholders ($) in the messages
.getReport()stringReturns the UID of the page where the problem was found
.getPage()stringReturn the page url where this issue occurred
.getFilename()stringReturns the filename where the problem was found
.getChain()stringReturns an array of certificates from the generated SSL chain. Each member of the chain will indicate what was expected. The order is expected to be as returned.
.getURL()stringReturns the url which is the subject of the url display type.
.getCode()stringReturns the code object that can be used to show code blocks for the occurrence, see Code Display Type.

Display Types

Each of the listed occurrences returns a display property indicating what known format the occurrence points to and how it should be displayed. This allows dynamic UI's that adapt according to the returned and processed data. The available display types include:

NameDescription
textGeneral/default type, indicating that only the text from message should be shown
urlIndicates that the occurrence refers to the specified url. For example images missing cache headers, would include the url to the image that might be missing the headers.
chainIndicates that the occurrence has to do with the SSL chain of the server. An array of certificates, with their status, of the correct SSL chain generated by our systems is included. This allows showing the complete SSL chain of a server, including which certificates are missing and correctly supplied. Each entry contains the actual required certificate to quickly copy or download for users.
codeIndicates that the problem found was found in code or some config. This display type will include a property to render code blocks with a highlighted section to show precisely where the problem exists in code.

The code display type

When occurrences are listed as the display type code, an object with information to render a code block is included. The details presented are:

NameTypeDescription
startnumberNumber of the line where the code block starts in the actual source code
endnumberNumber of the line where the code block ends in the actual source code
subjectnumberNumber of the line where the subject to focus on within the highlighted block is located
textarray[string]Array of strings that represent the actual code, starting at the start line. Then ending with the end line number

The chain display type

When occurrences are listed as the display type chain, an array of the correct chain is included. Each of the items in this chain refers to an certificate which will be shown as either missing or present. Each property includes the following information:

NameTypeDescription
pemarray[string]The actual certificate contents in an array using the PEM format, split up by new lines.
crlstringThe detected SSL Certificate Revocation List url that can be used to check the status of the certificate
commonNamestringThe common name from the certificate
altarray[string]Array of all the alt-names presented by the certificate
indexnumberIndex that the certificate is expected to be seen in the chain
typestringThe type of certificate, which is either:
  • user - Certificate generated for a specific server, or the current server testing
  • intermediate - Intermediate certificate from a CA
  • root - Root certificate of a CA
sourcestringSource where the certificate was found, which could be any of the following:
  • expected - The certificate was expected but not presented by the server
  • supplied - The certificate was supplied by the server being tested
signaturestringSignature of the included certificate
commonNamestringThe common name from the certificate
Signup icon
Ready to see how well your site scores?

Passmarked works best when you have an account. It allows you to keep a dashboard with saved data of the sites you have run through the system, we’ll alert you about important updates and you get access to the Passmarked Slack forum.

Sign up to get started