From d04c562d7e9637db1ef5d258017553438de87504 Mon Sep 17 00:00:00 2001 From: Jordan Wright Date: Thu, 3 Mar 2016 20:44:11 -0600 Subject: [PATCH] Updated API for release 0.1.2 --- templates/docs.html | 489 ++++++++++++++++++++++++++++++----------- templates/gophish.apib | 138 ++++++++++-- 2 files changed, 476 insertions(+), 151 deletions(-) diff --git a/templates/docs.html b/templates/docs.html index 8f9e493b..0d1f6045 100644 --- a/templates/docs.html +++ b/templates/docs.html @@ -1,5 +1,5 @@ {{ define "base" }} -Gophish API

Gophish API

API Endpoint
http://localhost:3333/api

Gophish was built from the ground-up with a JSON API that makes it easy for developers and sysadmins to automate simulated phishing campaigns.

+Gophish API

Gophish API

API Endpoint
http://localhost:3333/api

Gophish was built from the ground-up with a JSON API that makes it easy for developers and sysadmins to automate simulated phishing campaigns.

These docs describe how to use the gophish API.

Authorization

@@ -13,84 +13,7 @@ "data": null }
-

Campaigns

Campaigns object contain the resources needed for gophish to launch and track a simulated phishing campaign.

-

Campaigns have the following attributes:

-
    -
  • -

    id : 1 (number, required) - Unique identifier

    -
    • -
  • -

    name : Example Campaign (string, required) - Title of Campaign

    -
    • -
  • -

    created_date : 2015-1-1T01:02:03.000000Z (datetime) - Date the Campaign was created

    -
    • -
  • -

    completed_date : 2015-1-1T01:02:03.000000Z (datetime) - Date the Campaign was completed

    -
    • -
  • -

    template : Template

    -
    • -
  • -

    page : Page (required) - Landing page for users who click the phishing link

    -
    • -
  • -

    status : Emails Sent (string) - The current status of the campaign

    -
    • -
  • -

    results : array[Result] - List of Results for the campaign

    -
    • -
  • -

    timeline : array[Event] - List of Events for the campaign

    -
    • -
  • -

    smtp : SMTP

    -
    • -
  • -

    url : http://foo.bar (required, string) - The URL used in the Template sent to us -ers

    -
    • -
-

The results of the campaign are stored in the results field. Each result has the following attributes:

-
    -
  • -

    id : 1 (number, required) - Unique identifier

    -
    • -
  • -

    email : foo@example.com - Email address of the target

    -
    • -
  • -

    first_name : John - First name of the target

    -
    • -
  • -

    last_name : Doe - Last name of the target

    -
    • -
  • -

    status : Email Sent - The status of the result

    -
    • -
  • -

    ip : 1.2.3.4 - The IP address that created the event (if any)

    -
    • -
  • -

    latitude : 0.0000- The latitude of the IP address

    -
    • -
  • -

    longitude : 0.0000 - The longitude of the IP address

    -
    • -
-

Each campaign also keeps a timeline of events that occur, such as clicking a link, opening an email, etc. These events each have the following attributes:

-
    -
  • -

    email : foo@example.com - Email address of the target

    -
    • -
  • -

    time : 2015-1-1T01:02:03.000000Z (datetime) - The timestamp the event was created

    -
    • -
  • -

    message : Campaign Created (string) - The event message

    -
    • -
-

Campaigns

GET http://localhost:3333/api/campaigns
Responses200404
Headers
Content-Type: application/json
Body
[
+

Campaigns

Campaigns

GET http://localhost:3333/api/campaigns
Responses200404
Headers
Content-Type: application/json
Body
[
   {
     "id": 1,
     "name": "Example Campaign",
@@ -144,7 +67,8 @@ ers

       "host": "smtp.example.com:25",
       "username": "foo",
       "password": "bar",
-      "from_address": "John Doe <foo@example.com>"
+      "from_address": "John Doe <foo@example.com>",
+      "ignore_cert_errors": false
     },
     "url": "http://foo.bar"
   }
@@ -152,6 +76,83 @@ ers

   "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "array"
 }
Headers
Content-Type: application/json
Body
[]

Get Campaigns
GET/campaigns

Get a list of campaigns.

+

Campaigns object contain the resources needed for gophish to launch and track a simulated phishing campaign.

+

Campaigns have the following attributes:

+
    +
  • +

    id : 1 (number, required) - Unique identifier

    +
    • +
  • +

    name : Example Campaign (string, required) - Title of Campaign

    +
    • +
  • +

    created_date : 2015-1-1T01:02:03.000000Z (datetime) - Date the Campaign was created

    +
    • +
  • +

    completed_date : 2015-1-1T01:02:03.000000Z (datetime) - Date the Campaign was completed

    +
    • +
  • +

    template : Template

    +
    • +
  • +

    page : Page (required) - Landing page for users who click the phishing link

    +
    • +
  • +

    status : Emails Sent (string) - The current status of the campaign

    +
    • +
  • +

    results : array[Result] - List of Results for the campaign

    +
    • +
  • +

    timeline : array[Event] - List of Events for the campaign

    +
    • +
  • +

    smtp : SendingProfile

    +
    • +
  • +

    url : http://foo.bar (required, string) - The URL used in the Template sent to us +ers

    +
    • +
+

The results of the campaign are stored in the results field. Each result has the following attributes:

+
    +
  • +

    id : 1 (number, required) - Unique identifier

    +
    • +
  • +

    email : foo@example.com - Email address of the target

    +
    • +
  • +

    first_name : John - First name of the target

    +
    • +
  • +

    last_name : Doe - Last name of the target

    +
    • +
  • +

    status : Email Sent - The status of the result

    +
    • +
  • +

    ip : 1.2.3.4 - The IP address that created the event (if any)

    +
    • +
  • +

    latitude : 0.0000- The latitude of the IP address

    +
    • +
  • +

    longitude : 0.0000 - The longitude of the IP address

    +
    • +
+

Each campaign also keeps a timeline of events that occur, such as clicking a link, opening an email, etc. These events each have the following attributes:

+
    +
  • +

    email : foo@example.com - Email address of the target

    +
    • +
  • +

    time : 2015-1-1T01:02:03.000000Z (datetime) - The timestamp the event was created

    +
    • +
  • +

    message : Campaign Created (string) - The event message

    +
    • +
POST http://localhost:3333/api/campaigns
Requestsexample 1
Headers
Content-Type: application/json
Body
{
   "id": 1,
   "name": "Example Campaign",
@@ -205,7 +206,8 @@ ers

     "host": "smtp.example.com:25",
     "username": "foo",
     "password": "bar",
-    "from_address": "John Doe <foo@example.com>"
+    "from_address": "John Doe <foo@example.com>",
+    "ignore_cert_errors": false
   },
   "url": "http://foo.bar"
 }
Responses201400
Headers
Content-Type: application/json
Body
{
@@ -261,7 +263,8 @@ ers

     "host": "smtp.example.com:25",
     "username": "foo",
     "password": "bar",
-    "from_address": "John Doe <foo@example.com>"
+    "from_address": "John Doe <foo@example.com>",
+    "ignore_cert_errors": false
   },
   "url": "http://foo.bar"
 }
Schema
{
@@ -381,6 +384,10 @@ ers

         "from_address": {
           "type": "string",
           "description": "The \"From\" address to spoof"
+        },
+        "ignore_cert_errors": {
+          "type": "boolean",
+          "description": "Whether or not to ignore certificate errors"
         }
       },
       "required": [
@@ -390,7 +397,7 @@ ers

         "password",
         "from_address"
       ],
-      "description": "The SMTP settings used in the campaign"
+      "description": "The Sending Profile settings used in the campaign"
     },
     "url": {
       "type": "string",
@@ -477,7 +484,8 @@ ers

     "host": "smtp.example.com:25",
     "username": "foo",
     "password": "bar",
-    "from_address": "John Doe <foo@example.com>"
+    "from_address": "John Doe <foo@example.com>",
+    "ignore_cert_errors": false
   },
   "url": "http://foo.bar"
 }
Schema
{
@@ -597,6 +605,10 @@ ers

         "from_address": {
           "type": "string",
           "description": "The \"From\" address to spoof"
+        },
+        "ignore_cert_errors": {
+          "type": "boolean",
+          "description": "Whether or not to ignore certificate errors"
         }
       },
       "required": [
@@ -606,7 +618,7 @@ ers

         "password",
         "from_address"
       ],
-      "description": "The SMTP settings used in the campaign"
+      "description": "The Sending Profile settings used in the campaign"
     },
     "url": {
       "type": "string",
@@ -635,7 +647,28 @@ ers

   "data": null
 }

Delete a Campaign
DELETE/campaigns/{id}

Delete a campaign by its ID.

URI Parameters
HideShow
id
number (required) Example: 1

The Campaign ID

-

Templates

Templates define what email content is sent to targets during campaigns. It contains the subject of the email as well as the HTML and text content of the email.

+

Templates

Templates

GET http://localhost:3333/api/templates
Responses200404
Headers
Content-Type: application/json
Body
[
+  {
+    "id": 1,
+    "name": "Example Template",
+    "subject": "Example email template subject",
+    "text": "This is a test message!",
+    "html": "<html><head></head><body>This is a test message!</body></html>",
+    "attachments": [
+      {
+        "id": 1,
+        "name": "Example Attachment",
+        "content": "Hello, world!",
+        "type": "text/plain"
+      }
+    ],
+    "modified_date": "2015-01-01T01:02:03.000000Z"
+  }
+]
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "array"
+}
Headers
Content-Type: application/json
Body
[]

Get Templates
GET/templates

Get a list of templates.

+

Templates define what email content is sent to targets during campaigns. It contains the subject of the email as well as the HTML and text content of the email.

  • id: 1 (number, required) - Unique identifier

    @@ -675,27 +708,6 @@ ers

    type: text/plain - MIME type of the Attachment

-

Templates

GET http://localhost:3333/api/templates
Responses200404
Headers
Content-Type: application/json
Body
[
-  {
-    "id": 1,
-    "name": "Example Template",
-    "subject": "Example email template subject",
-    "text": "This is a test message!",
-    "html": "<html><head></head><body>This is a test message!</body></html>",
-    "attachments": [
-      {
-        "id": 1,
-        "name": "Example Attachment",
-        "content": "Hello, world!",
-        "type": "text/plain"
-      }
-    ],
-    "modified_date": "2015-01-01T01:02:03.000000Z"
-  }
-]
Schema
{
-  "$schema": "http://json-schema.org/draft-04/schema#",
-  "type": "array"
-}
Headers
Content-Type: application/json
Body
[]

Get Templates
GET/templates

Get a list of templates.

POST http://localhost:3333/api/templates
Requestsexample 1
Headers
Content-Type: application/json
Body
{
   "id": 1,
   "name": "Example Template",
@@ -894,7 +906,18 @@ ers

   "data": null
 }

Delete a Template
DELETE/templates/{id}

Delete a template by its ID.

URI Parameters
HideShow
id
number (required) Example: 1

The Template ID

-

Groups

Groups contain the details for one or more users targeted in the simulated phishing campaign. Groups contain the following attributes:

+

Groups

Groups

GET http://localhost:3333/api/groups
Responses200404
Headers
Content-Type: application/json
Body
[
+  {
+    "id": 1,
+    "name": "Example Group",
+    "modified_date": "2015-01-01T01:02:03.000000Z",
+    "targets": "array[Target]"
+  }
+]
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "array"
+}
Headers
Content-Type: application/json
Body
[]

Get Groups
GET/groups

Get a list of groups.

+

Groups contain the details for one or more users targeted in the simulated phishing campaign. Groups contain the following attributes:

  • id: 1 (required, number) - Unique identifier

    @@ -932,17 +955,6 @@ ers

    If you have all your targets in a CSV file, you can bulk import them into a group using the Import CSV endpoint.

    In the future, we plan to add other importation methods to make setting up groups a breeze.

-

Groups

GET http://localhost:3333/api/groups
Responses200404
Headers
Content-Type: application/json
Body
[
-  {
-    "id": 1,
-    "name": "Example Group",
-    "modified_date": "2015-01-01T01:02:03.000000Z",
-    "targets": "array[Target]"
-  }
-]
Schema
{
-  "$schema": "http://json-schema.org/draft-04/schema#",
-  "type": "array"
-}
Headers
Content-Type: application/json
Body
[]

Get Groups
GET/groups

Get a list of groups.

POST http://localhost:3333/api/groups
Requestsexample 1
Headers
Content-Type: application/json
Body
{
   "id": 1,
   "name": "Example Group",
@@ -1073,7 +1085,231 @@ ers

   "data": null
 }

Delete a Group
DELETE/groups/{id}

Delete a Group by its ID.

URI Parameters
HideShow
id
number (required) Example: 1

The Template ID

-

Pages

Pages are the HTML page that a user lands on after clicking on a phishing link.

+

Sending Profiles

Sending Profiles

GET http://localhost:3333/api/smtp
Responses200404
Headers
Content-Type: application/json
Body
[
+  {
+    "id": 1,
+    "host": "smtp.example.com:25",
+    "username": "foo",
+    "password": "bar",
+    "from_address": "John Doe <foo@example.com>",
+    "ignore_cert_errors": false
+  }
+]
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "array"
+}
Headers
Content-Type: application/json
Body
[]

Get Sending Profiles
GET/smtp

Get a list of sending profiles.

+

Sending profiles contain the details for SMTP or other settings used to control how emails are sent in campaigns. Sending profiles contain the following attributes:

+
    +
  • +

    id: 1 (required, number) - Unique identifier

    +
    • +
  • +

    name: Example Profile (string, required) - Name of the Sending Profile

    +
    • +
  • +

    interface: SMTP (string) - Interface type of the sending profile. By default, this is “SMTP”

    +
    • +
  • +

    host: 1.1.1.1:25 (string, required) - The hostname:port for the SMTP configuration

    +
    • +
  • +

    username: foo (string) - The username to authenticate to the SMTP server (optional)

    +
    • +
  • +

    password: bar (string) - The password to authenticate to the SMTP server (optional)

    +
    • +
  • +

    from_address: Foo Bar foo.bar@example.com (string) - The email address to use in the “From” header. This is typically used to spoof email addresses

    +
    • +
  • +

    ignore_cert_errors: false (boolean) - Whether or not to disable certificate validation when connecting to the SMTP server via TLS

    +
    • +
  • +

    modified_date: 2015-01-01T01:02:03.000000Z (string) - Date the Group was last modified

    +
    • +
+
+

Receiving Certificate Errors?

+

It’s common to have an SMTP server that is configured using a self-signed or otherwise untrusted SSL certficate. To avoid errors when connecting to the server, set ignore_cert_errors to “true”.

+
+
POST http://localhost:3333/api/smtp
Requestsexample 1
Headers
Content-Type: application/json
Body
{
+  "id": 1,
+  "host": "smtp.example.com:25",
+  "username": "foo",
+  "password": "bar",
+  "from_address": "John Doe <foo@example.com>",
+  "ignore_cert_errors": false
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "number",
+      "description": "Unique identifier"
+    },
+    "host": {
+      "type": "string",
+      "description": "The hostname and port for the SMTP server"
+    },
+    "username": {
+      "type": "string",
+      "description": "The username used for SMTP authentication"
+    },
+    "password": {
+      "type": "string",
+      "description": "The password used for SMTP authentication"
+    },
+    "from_address": {
+      "type": "string",
+      "description": "The \"From\" address to spoof"
+    },
+    "ignore_cert_errors": {
+      "type": "boolean",
+      "description": "Whether or not to ignore certificate errors"
+    }
+  },
+  "required": [
+    "id",
+    "host",
+    "username",
+    "password",
+    "from_address"
+  ]
+}
Responses201400
Headers
Content-Type: application/json
Body
{
+  "id": 1,
+  "host": "smtp.example.com:25",
+  "username": "foo",
+  "password": "bar",
+  "from_address": "John Doe <foo@example.com>",
+  "ignore_cert_errors": false
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "number",
+      "description": "Unique identifier"
+    },
+    "host": {
+      "type": "string",
+      "description": "The hostname and port for the SMTP server"
+    },
+    "username": {
+      "type": "string",
+      "description": "The username used for SMTP authentication"
+    },
+    "password": {
+      "type": "string",
+      "description": "The password used for SMTP authentication"
+    },
+    "from_address": {
+      "type": "string",
+      "description": "The \"From\" address to spoof"
+    },
+    "ignore_cert_errors": {
+      "type": "boolean",
+      "description": "Whether or not to ignore certificate errors"
+    }
+  },
+  "required": [
+    "id",
+    "host",
+    "username",
+    "password",
+    "from_address"
+  ]
+}
Headers
Content-Type: application/json
Body
{
+  "message": "Error message",
+  "success": false,
+  "data": "Any associated data"
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "message": {
+      "type": "string",
+      "description": "The detailed error message"
+    },
+    "success": {
+      "type": "boolean",
+      "description": "The success status of the request"
+    },
+    "data": {
+      "type": "string"
+    }
+  }
+}

Create New Sending Profile
POST/smtp

Create a new sending profile

+

Sending Profile

GET http://localhost:3333/api/smtp/1
Responses200404
Headers
Content-Type: application/json
Body
{
+  "id": 1,
+  "host": "smtp.example.com:25",
+  "username": "foo",
+  "password": "bar",
+  "from_address": "John Doe <foo@example.com>",
+  "ignore_cert_errors": false
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "number",
+      "description": "Unique identifier"
+    },
+    "host": {
+      "type": "string",
+      "description": "The hostname and port for the SMTP server"
+    },
+    "username": {
+      "type": "string",
+      "description": "The username used for SMTP authentication"
+    },
+    "password": {
+      "type": "string",
+      "description": "The password used for SMTP authentication"
+    },
+    "from_address": {
+      "type": "string",
+      "description": "The \"From\" address to spoof"
+    },
+    "ignore_cert_errors": {
+      "type": "boolean",
+      "description": "Whether or not to ignore certificate errors"
+    }
+  },
+  "required": [
+    "id",
+    "host",
+    "username",
+    "password",
+    "from_address"
+  ]
+}
Headers
Content-Type: application/json
Body
{
+  "message": "SMTP not found",
+  "success": false,
+  "data": null
+}

Get Sending Profile
GET/smtp/{id}

Get a sending profile by its ID.

+
URI Parameters
HideShow
id
number (required) Example: 1

The sending profile ID

+
DELETE http://localhost:3333/api/smtp/1
Responses200404
Headers
Content-Type: application/json
Body
{
+  "message": "SMTP deleted successfully!",
+  "success": true,
+  "data": null
+}
Headers
Content-Type: application/json
Body
{
+  "message": "SMTP not found",
+  "success": false,
+  "data": null
+}

Delete a Sending Profile
DELETE/smtp/{id}

Delete a Sending Profile by its ID.

+
URI Parameters
HideShow
id
number (required) Example: 1

The Sending Profile ID

+

Pages

Pages

GET http://localhost:3333/api/pages
Responses200404
Headers
Content-Type: application/json
Body
[
+  {
+    "id": 1,
+    "name": "Example Page",
+    "html": "<html><head></head><body>This is a test message!</body></html>",
+    "modified_date": "2015-01-01T01:02:03.000000Z"
+  }
+]
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "array"
+}
Headers
Content-Type: application/json
Body
[]

Get Pages
GET/pages

Get a list of pages. +Pages are the HTML page that a user lands on after clicking on a phishing link.

  • id: 1 (required, number) - Unique identifier

    @@ -1092,17 +1328,6 @@ ers

    Importing a Site

    Let gophish do the hard work for you in importing a site. By using the Import Site endpoint, you can simply give gophish a URL and have the site imported for you.

-

Pages

GET http://localhost:3333/api/pages
Responses200404
Headers
Content-Type: application/json
Body
[
-  {
-    "id": 1,
-    "name": "Example Page",
-    "html": "<html><head></head><body>This is a test message!</body></html>",
-    "modified_date": "2015-01-01T01:02:03.000000Z"
-  }
-]
Schema
{
-  "$schema": "http://json-schema.org/draft-04/schema#",
-  "type": "array"
-}
Headers
Content-Type: application/json
Body
[]

Get Pages
GET/pages

Get a list of pages.

POST http://localhost:3333/api/pages
Requestsexample 1
Headers
Content-Type: application/json
Body
{
   "id": 1,
   "name": "Example Page",
@@ -1486,7 +1711,7 @@ Content-Type: text/html; charset=UTF-8
   }
 }

Import a Site
POST/import/site

Imports a site via the URL. This causes gophish to reach out to the site and pull down the HTML of the URL given.

To keep styles, images, and Javascript setup and working, gophish adds a base tag to the returned HTML pointing to the original site.

-

Generated by aglio on 12 Jan 2016