@hardenize/api
Isomorphic JS client library for Hardenize API
Last updated 17 days ago by mikehardenize .
Apache-2.0 · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install @hardenize/api 
SYNC missed versions from official npm registry.

Hardenize API

This is an isomorphic javascript client library for accessing the Hardenize Org API

Although it is isomorphic, you will almost always only want to use it from inside NodeJS. That is because if you use it from a web browser, you will expose your Hardenize API credentials, which you MUST keep secret.

Install

$ npm i @hardenize/api

Or:

$ git clone https://github.com/hardenize/hardenize-api

If you are targetting the browser and do not have a build pipeline using something like webpack or browserify, you can grab a copy of static.js from the root of the git repository, place it on your website somewhere and then include it using a script tag. This will expose window.HardenizeApi

If you are targetting old web browsers, ensure that fetch and Promise are polyfilled as this lib expects them to exist.

Setup

import HardenizeApi from '@hardenize/api';

const api = new HardenizeApi({
    user: 'your_api_username',
    pass: 'your_api_password',
    org:  'your_org_label',
});

Once you have an api object, you can call a number of methods on it. Each one of them will return a Promise.

Successful API calls are resolved with an object containing data and res, where data is the API response body, and res is the HTTP Response object. res exists, so that you can do things like checking the HTTP response status code.

Failed API calls are rejected with an Error object containing the error message. It MAY also include a res HTTP Response object also if the call got as far as making a HTTP request and receiving a HTTP response.

A basic example:

(async () => {
    try {
        const { data, res } = await api.getCerts();
        console.log(data.certs);
    } catch(err) {
        if (err.res) console.warn(`API Response Status: ${err.res.status} ${err.res.statusText}`);
        console.warn(err.message)
    }
})();

The above example uses async, await and appropriate error handling. The remainder of the examples in this documentation will drop suitable error handling and ignore the async wrapper, for brevity.

Events

For tracing/debugging, it can sometimes be useful to track all API requests sent and responses received. You can add listeners for these events on a HardenizeAPI object. Your callback will be passed a Request or Response object as an argument. Examples:

const api = new HardenizeApi({ ...options });

const onRequest      = req  => console.log("Sending API request",        req);
const onResponse     = res  => console.log("Received API response",      res);
const onResponseBody = body => console.log("Received API response body", body);

api.addEventListener('request',  onRequest);
api.addEventListener('response', onResponse);
api.addEventListener('body',     onResponseBody);

// Or:
api.on('request',  onRequest);
api.on('response', onResponse);
api.on('body',     onResponseBody);

To remove the event listeners:

api.removeEventListener('request',  onRequest);
api.removeEventListener('response', onResponse);
api.removeEventListener('body',     onResponseBody);

// Or:
api.off('request',  onRequest);
api.off('response', onResponse);
api.off('body',     onResponseBody);

If you want to remove all of the event listeners of a particular type, just don't pass the callback function argument:

api.removeEventListener('request');
api.removeEventListener('response');
api.removeEventListener('body');

// Or:
api.off('request');
api.off('response');
api.off('body');

Methods

version()

Returns the api version string. Can also be called as a class function. E.g:

import HardenizeApi from '@hardenize/api';

const api = new HardenizeApi({ config });

HardenizeApi.version() === api.version();

config(name, value)

Allows you to view or change configuration on an existing API object. Examples:

api.config();                           // View all config
api.config('user');                     // View just config.user
api.config('user', 'foo');              // Change user to foo
api.config('user', null);               // Delete user from config
api.config({ pass: 'foo', org: null }); // Change pass to foo and delete org

getCerts(options)

See https://www.hardenize.com/docs/api/v1/#list-certificates

Example. Fetch all active certificates that have not yet expired, but will expire within the next 30 days.

const { data: { certs } } = await api.getCerts({ active: true, expired: false, expireInDays: 30 });

getCert(sha256)

See https://www.hardenize.com/docs/api/v1/#retrieve-certificate

Example. Fetch a certificate with a particular SHA256.

const { data: { cert } } = await api.getCert('3c8031d6af1dc0a557381318692f0d4ecb74508e2116d489fec9dcc16a0f1552');

createCert(pem)

See https://www.hardenize.com/docs/api/v1/#create-certificate

Example. Create a certificate with a particular PEM

const { res, data: { sha256 } } = await api.createCert('some pem content');
switch (res.status) {
    case 201: console.log('Certificate created',         sha256); break;
    case 202: console.log('Certificate already existed', sha256); break;
    default: // Should not get as far as this
}

createDnsZone(root, zoneBody)

See https://www.hardenize.com/docs/api/v1/#upload-dns-zone

Example. Create a dns zone for "example.com"

const zoneBody = `$ORIGIN example.com.
$TTL 1h
@      IN  SOA   ns.example.com. admin.example.com. ( 2018081601 1d 2h 4w 1h )
@      IN  NS    ns
@      IN  MX    10 mx.example.com.
@      IN  A     192.0.2.1
       IN  AAAA  2001:db8:10::1
ns     IN  A     192.0.2.2
       IN  AAAA  2001:db8:10::2
www    IN  CNAME example.com.
mx     IN  A     192.0.2.3`;

await api.createDnsZone('example.com', zoneBody);

getGroups()

See https://www.hardenize.com/docs/api/v1/#list-groups

Fetch a list of groups.

const { data: { groups } } = await api.getGroups();

createGroup(id, options)

See https://www.hardenize.com/docs/api/v1/#create-group

Create a new group

await api.createGroup('groupid', { name: 'Group Name' });

deleteGroup(id, options)

See https://www.hardenize.com/docs/api/v1/#delete-group

Delete a group

await api.deleteGroup('groupid');

This will fail if the group is in use. If you want to force removal even if the group is in use, pass an additional object with force set to true:

await api.deleteGroup('groupid', { force: true });

getHosts(options)

See https://www.hardenize.com/docs/api/v1/#list-hosts

Fetch a list of hosts

const { data: { hosts } } = await api.getHosts();

getHost(hostname)

See https://www.hardenize.com/docs/api/v1/#retrieve-host

Fetch details about a host

const { data: { host } } = await api.getHost('example.com');

createHosts(hostnames, options)

See https://www.hardenize.com/docs/api/v1/#create-hosts

Create new hosts

await api.createHosts([ 'example.com', 'example.org' ], {
    status: 'monitored',
    groups: ['Production'],
});

updateHosts(hostnames, changes, options)

See https://www.hardenize.com/docs/api/v1/#update-hosts

Update hosts.

Example: Update example.com, example.org and all hosts that are subdomains of those two hostnames. Set their statuses to 'idle', and add a group named "New" to each of them.

await api.updateHosts([ 'example.com', 'example.org' ], {
    status:  'idle',
    groups:  ['New'],
    groupOp: 'add',
}, {
    subdomains: true,
});

deleteHosts(hostnames, options)

See https://www.hardenize.com/docs/api/v1/#delete-hosts

Delete hosts

await api.deleteHosts([ 'example.com', 'example.org' ]);

getHostDiscoveries()

See https://www.hardenize.com/docs/api/v1/#list-host-discoveries

Gets a list of host discoveries.

Example: Fetch keyword related pending discoveries.

const { data: { hostDiscoveries } } = await api.getHostDiscoveries({
    triageResolution: 'pending',
    matchReason:      'keyword',
});

getHostDiscovery(id)

See https://www.hardenize.com/docs/api/v1/#retrieve-host-discovery

Retrieves a host discovery, by ID. Id's can be seen in the results of calling getHostDiscoveries().

const { data: { hostDiscovery } } = await api.getHostDiscovery(id);

updateHostDiscovery(id, options)

See https://www.hardenize.com/docs/api/v1/#update-host-discovery

Updates an existing host discovery. Allows setting the triage resolution and effective hostname.

await api.updateHostDiscovery(id, {
    triageResolution: 'own',
    effectiveHostname: 'hardenize.com',
});

createHostDiscoveryKeyword(keyword, options)

See https://www.hardenize.com/docs/api/v1/#create-host-discovery-keyword

Create a new host discovery keyword.

Example: Create a host discovery keyword of "hardenize", excluding matching hosts if they contain the substring "test" or are a subdomain of "example.com".

await api.createHostDiscoveryKeyword('hardenize', {
    exclusions: [{
        type: 'substring',
        exclusion: 'test',
    }, {
        type: 'subdomain',
        exclusion: 'example.com',
    }]
});

deleteHostDiscoveryKeyword(keyword)

See https://www.hardenize.com/docs/api/v1/#delete-host-discovery-keyword

Delete a host discovery keyword.

await api.deleteHostDiscoveryKeyword('hardenize');

getHostDiscoveryKeywords()

See https://www.hardenize.com/docs/api/v1/#list-host-discovery-keywords

Gets the list of host discovery keywords.

const { data: { hostDiscoveryKeywords } } = await api.getHostDiscoveryKeywords();

getHostDiscoveryKeyword(keyword)

See https://www.hardenize.com/docs/api/v1/#retrieve-host-discovery-keyword

Gets a host discovery keyword.

const { data: { hostDiscoveryKeyword } } = await api.getHostDiscoveryKeyword('hardenize');

getReports0(options)

See https://www.hardenize.com/docs/api/v1/#list-report-summaries

Fetch a list of reports.

Example: Fetch a list of reports for example.com and it's subdomains. Only include those with the production group.

const { data: { reports } } = await api.getReports0({
    name:       'example.com',
    subdomains: true,
    group:      'production'
});

getSubOrgs()

See https://www.hardenize.com/docs/api/v1/#list-organizations

Fetch a list of organizations.

Example:

const { data: { orgs } } = await api.getSubOrgs();

createSubOrg(id, options)

See https://www.hardenize.com/docs/api/v1/#create-organization

Create a sub organization to your account.

Example: Create an organization with an id of example, a display name of Example Ltd. Set its initial status to dormant, and generate api credentials for it.

const { data: { org } } = await api.createSubOrg('example', {
    name:                   'Example Ltd',
    status:                 'dormant',
    generateApiCredentials: true,
});

updateSubOrg

See https://www.hardenize.com/docs/api/v1/#update-organization

Update an organization in your account.

Example: Update the status of an organization to active and regenerate it's API credentials

const { data: { org } } = await api.updateSubOrg('example', {
    status:                 'active',
    generateApiCredentials: true,
});

deleteSubOrg

See https://www.hardenize.com/docs/api/v1/#delete-organization

Delete an organization from your account.

Example:

await api.deleteSubOrg('example');

getEventTypes()

See https://www.hardenize.com/docs/api/v1/#list-event-types

Fetch a list of event types

Example:

await api.getEventTypes();

updateEventType(name, options)

See https://www.hardenize.com/docs/api/v1/#update-event-type

Update an event type.

Example: Disabling the "example.type" event type:

await api.updateEventType('example.type', { enabled: false });

getEvents(options)

See https://www.hardenize.com/docs/api/v1/#list-events

Get a list of events.

Example: Fetch a list of events (up to a max of 3), that have occured since a particular date/time, for a particular type only.

await api.getEvents({ type: 'example.type', since: '2018-06-20T12:05:12.123456Z', limit: 3 });

getEvent(id)

See https://www.hardenize.com/docs/api/v1/#get-event

Example:

await api.getEvent(5);

createEventHook(options)

See https://www.hardenize.com/docs/api/v1/#create-event-hook

Create an event hook.

Example:

const { eventHook } = await api.createEventHook({
  hookType:    'webhook',
  eventTypes:  ['ct.entry'],
  destination: 'https://www.example.com/webhooks/receive',
});

deleteEventHook(id)

See https://www.hardenize.com/docs/api/v1/#delete-event-hook

Delete an event hook.

Example:

await api.deleteEventHook('24673847d5cb283205568e34f8855ba2');

getEventHooks()

See https://www.hardenize.com/docs/api/v1/#list-event-hooks

Get a list of your event hooks.

Example:

const { eventHooks } = await api.getEventHooks();

getEventHookDestinations()

See https://www.hardenize.com/docs/api/v1/#list-event-destinations

Get a list of your event hook destinations.

Example:

const { eventDestinations } = await api.getEventHookDestinations();

testEventHook(id, options)

See https://www.hardenize.com/docs/api/v1/#test-event-hook

Test an event hook.

Example: Test with an invalid signature

const result = await api.testEventHook('24673847d5cb283205568e34f8855ba2', { invalid: 'signature' });

updateEventHook(id, changes)

See https://www.hardenize.com/docs/api/v1/#update-event-hook

Update an event hook.

Example: Set the status to enabled

const { eventHook } = await api.updateEventHook('24673847d5cb283205568e34f8855ba2', { status: 'enabled' });

updateUser(id, options)

See https://www.hardenize.com/docs/api/v1/#update-user

Update user.

Example: Disable MFA for user id 1.

await api.updateUser(1, { deleteMfa: true });

Development

If you are a core developer of this library (you almost certainly aren't, unless you work for Hardenize Limited), you should check out ./DEVELOPMENT.md

Current Tags

  • 0.18.0                                ...           latest (17 days ago)

38 Versions

  • 0.18.0                                ...           17 days ago
  • 0.17.0                                ...           4 months ago
  • 0.16.0                                ...           4 months ago
  • 0.15.0                                ...           5 months ago
  • 0.14.0                                ...           6 months ago
  • 0.13.0                                ...           8 months ago
  • 0.12.0                                ...           8 months ago
  • 0.11.3                                ...           8 months ago
  • 0.11.2                                ...           8 months ago
  • 0.11.1                                ...           8 months ago
  • 0.11.0                                ...           9 months ago
  • 0.10.1                                ...           9 months ago
  • 0.10.0                                ...           9 months ago
  • 0.9.0                                ...           10 months ago
  • 0.8.0                                ...           10 months ago
  • 0.7.1                                ...           10 months ago
  • 0.7.0                                ...           10 months ago
  • 0.6.0                                ...           10 months ago
  • 0.5.0                                ...           10 months ago
  • 0.4.1                                ...           10 months ago
  • 0.4.0                                ...           10 months ago
  • 0.3.1                                ...           10 months ago
  • 0.2.0                                ...           a year ago
  • 0.1.14                                ...           a year ago
  • 0.1.13                                ...           a year ago
  • 0.1.12                                ...           a year ago
  • 0.1.11                                ...           a year ago
  • 0.1.10                                ...           a year ago
  • 0.1.9                                ...           a year ago
  • 0.1.8                                ...           a year ago
  • 0.1.7                                ...           a year ago
  • 0.1.6                                ...           a year ago
  • 0.0.6                                ...           a year ago
  • 0.0.5                                ...           a year ago
  • 0.0.4                                ...           a year ago
  • 0.0.3                                ...           a year ago
  • 0.0.2                                ...           a year ago
  • 0.0.1                                ...           a year ago
Maintainers (1)
Downloads
Today 0
This Week 0
This Month 134
Last Day 0
Last Week 0
Last Month 38
Dependencies (1)
Dev Dependencies (2)
Dependents (1)

Copyright 2014 - 2016 © taobao.org |