From 5b3c95249992503ab0e69d93eb1699e81a5091ba Mon Sep 17 00:00:00 2001 From: Jordan Wright Date: Sat, 26 Dec 2015 20:48:10 -0600 Subject: [PATCH] Added some notes around importation. Fixed some errors in the API docs. Closes #45 --- templates/docs.html | 314 +++++------------------------------------ templates/gophish.apib | 69 +++++++-- 2 files changed, 92 insertions(+), 291 deletions(-) diff --git a/templates/docs.html b/templates/docs.html index ca0d8c49..474abbe7 100644 --- a/templates/docs.html +++ b/templates/docs.html @@ -1,5 +1,5 @@ -{{define "base"}} -Gophish API Back to top

Gophish 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.

+{{ define "base" }} +Gophish API Back to top

Gophish 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

@@ -29,10 +29,10 @@

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

  • -

    template : Template

    +

    template : Template

  • -

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

    +

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

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

    @@ -543,148 +543,9 @@ ers

    }

    • Delete a Campaign
    DELETE/campaigns/{id}

    Delete a campaign by its ID.

    Parameters
    HideShow
    id
    number (required) Example: 1

    The Campaign ID

    Response  200
    HideShow
    Headers
    Content-Type: application/json
    Body
    {
-  "id": 1,
-  "name": "Example Campaign",
-  "created_date": "2015-01-01T01:02:03.000000Z",
-  "completed_date": "2015-01-01T01:02:03.000000Z",
-  "template": {
-    "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": [],
-    "modified_date": "2015-01-01T01:02:03.000000Z"
-  },
-  "page": {
-    "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"
-  },
-  "status": "Emails Sent",
-  "results": [],
-  "timeline": [],
-  "smtp": {
-    "id": 1
-  },
-  "url": "http://foo.bar"
-}
    Schema
    {
-  "type": "object",
-  "properties": {
-    "id": {
-      "type": "number",
-      "description": "Unique identifier"
-    },
-    "name": {
-      "type": "string",
-      "description": "Title of Campaign"
-    },
-    "created_date": {
-      "type": "string",
-      "description": "Date the Campaign was created"
-    },
-    "completed_date": {
-      "type": "string",
-      "description": "Date the Campaign was completed"
-    },
-    "template": {
-      "type": "object",
-      "properties": {
-        "id": {
-          "type": "number",
-          "description": "Unique identifier"
-        },
-        "name": {
-          "type": "string",
-          "description": "Name of template"
-        },
-        "subject": {
-          "type": "string",
-          "description": "Subject of email sent to users"
-        },
-        "text": {
-          "type": "string",
-          "description": "Raw text of email sent to users"
-        },
-        "html": {
-          "type": "string",
-          "description": "HTML of email sent to users"
-        },
-        "attachments": {
-          "type": "array",
-          "description": "The attachments sent with the email template"
-        },
-        "modified_date": {
-          "type": "string",
-          "description": "Date the Template was last modified"
-        }
-      },
-      "required": [
-        "id",
-        "name"
-      ]
-    },
-    "page": {
-      "type": "object",
-      "properties": {
-        "id": {
-          "type": "number",
-          "description": "Unique identifier"
-        },
-        "name": {
-          "type": "string",
-          "description": "Name of Page"
-        },
-        "html": {
-          "type": "string",
-          "description": "HTML of the landing page users hit when clicking links in the email template"
-        },
-        "modified_date": {
-          "type": "string",
-          "description": "Date the Page was last modified"
-        }
-      },
-      "required": [
-        "id",
-        "name",
-        "html"
-      ]
-    },
-    "status": {
-      "type": "string",
-      "description": "The current status of the campaign"
-    },
-    "results": {
-      "type": "array"
-    },
-    "timeline": {
-      "type": "array"
-    },
-    "smtp": {
-      "type": "object",
-      "properties": {
-        "id": {
-          "type": "number",
-          "description": "Unique identifier"
-        }
-      },
-      "required": [
-        "id"
-      ]
-    },
-    "url": {
-      "type": "string",
-      "description": "The URL used in the Template sent to users"
-    }
-  },
-  "required": [
-    "id",
-    "name",
-    "status",
-    "url"
-  ],
-  "$schema": "http://json-schema.org/draft-04/schema#"
+  "message": "Page deleted successfully!",
+  "success": true,
+  "data": null
 }
    Response  404
    HideShow
    Headers
    Content-Type: application/json
    Body
    {
   "message": "Campaign not found",
   "success": false,
@@ -744,6 +605,11 @@ ers
    
   "type": "array",
   "$schema": "http://json-schema.org/draft-04/schema#"
 }

    Create New Template
    POST/templates

    Create a new template

    +
    +

    Importing an Existing Email

    +

    What better way to make pixel-perfect emails than by importing an existing email you already have sitting in your inbox?

    +

    Using the Import Email endpoint, you can take a raw email and import it as a template into gophish.

    +
    Request
    HideShow
    Headers
    Content-Type: application/json
    Body
    {
   "id": 1,
   "name": "Example Template",
@@ -908,50 +774,9 @@ ers
    
 }

    Delete a Template
    DELETE/templates/{id}

    Delete a template by its ID.

    Parameters
    HideShow
    id
    number (required) Example: 1

    The Template ID

    Response  200
    HideShow
    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": [],
-  "modified_date": "2015-01-01T01:02:03.000000Z"
-}
    Schema
    {
-  "type": "object",
-  "properties": {
-    "id": {
-      "type": "number",
-      "description": "Unique identifier"
-    },
-    "name": {
-      "type": "string",
-      "description": "Name of template"
-    },
-    "subject": {
-      "type": "string",
-      "description": "Subject of email sent to users"
-    },
-    "text": {
-      "type": "string",
-      "description": "Raw text of email sent to users"
-    },
-    "html": {
-      "type": "string",
-      "description": "HTML of email sent to users"
-    },
-    "attachments": {
-      "type": "array",
-      "description": "The attachments sent with the email template"
-    },
-    "modified_date": {
-      "type": "string",
-      "description": "Date the Template was last modified"
-    }
-  },
-  "required": [
-    "id",
-    "name"
-  ],
-  "$schema": "http://json-schema.org/draft-04/schema#"
+  "message": "Template deleted successfully!",
+  "success": true,
+  "data": null
 }
    Response  404
    HideShow
    Headers
    Content-Type: application/json
    Body
    {
   "message": "Template not found",
   "success": false,
@@ -989,6 +814,11 @@ ers
    
 
    position: System Administrator - Company position of the Target
    
 
 
+
    
+
    Have A Lot of Users to Import? 
    
+
    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 Groups
    GET/groups
    Get a list of groups.
    
 
    Response  200
    HideShow
    Headers
    Content-Type: application/json
    Body
    [
   {
@@ -1117,56 +947,14 @@ ers
    
 }
    Delete a Group
    DELETE/groups/{id}
    Delete a Group by its ID.
    
 
    Parameters
    HideShow
    id
    number (required) Example: 1
    The Template ID
    
 
    Response  200
    HideShow
    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": [],
-  "modified_date": "2015-01-01T01:02:03.000000Z"
-}
    Schema
    {
-  "type": "object",
-  "properties": {
-    "id": {
-      "type": "number",
-      "description": "Unique identifier"
-    },
-    "name": {
-      "type": "string",
-      "description": "Name of template"
-    },
-    "subject": {
-      "type": "string",
-      "description": "Subject of email sent to users"
-    },
-    "text": {
-      "type": "string",
-      "description": "Raw text of email sent to users"
-    },
-    "html": {
-      "type": "string",
-      "description": "HTML of email sent to users"
-    },
-    "attachments": {
-      "type": "array",
-      "description": "The attachments sent with the email template"
-    },
-    "modified_date": {
-      "type": "string",
-      "description": "Date the Template was last modified"
-    }
-  },
-  "required": [
-    "id",
-    "name"
-  ],
-  "$schema": "http://json-schema.org/draft-04/schema#"
+  "message": "Group deleted successfully!",
+  "success": true,
+  "data": null
 }
    Response  404
    HideShow
    Headers
    Content-Type: application/json
    Body
    {
   "message": "Group not found",
   "success": false,
   "data": null
-}
    Pages
    Campaigns object contain the resources needed for gophish to launch and track a simulated phishing campaign.
    
-
    Pages
    Pages are the HTML page that a user lands on after clicking on a phishing link.
    
+}

    Pages

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

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

      @@ -1181,7 +969,11 @@ ers

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

    -

    Get Pages
    GET/pages

    Get a list of templates.

    +
    +

    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 Pages
    GET/pages

    Get a list of pages.

    Response  200
    HideShow
    Headers
    Content-Type: application/json
    Body
    [
   {
     "id": 1,
@@ -1345,49 +1137,19 @@ ers
    
   ],
   "$schema": "http://json-schema.org/draft-04/schema#"
 }
    Response  404
    HideShow
    Headers
    Content-Type: application/json
    Body
    {
-  "message": "Group not found",
+  "message": "Page not found",
   "success": false,
   "data": null
 }

    Delete a Page
    DELETE/pages/{id}

    Delete a page by its ID.

    Parameters
    HideShow
    id
    number (required) Example: 1

    The Page ID

    Response  200
    HideShow
    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
    {
-  "type": "object",
-  "properties": {
-    "id": {
-      "type": "number",
-      "description": "Unique identifier"
-    },
-    "name": {
-      "type": "string",
-      "description": "Name of Page"
-    },
-    "html": {
-      "type": "string",
-      "description": "HTML of the landing page users hit when clicking links in the email template"
-    },
-    "modified_date": {
-      "type": "string",
-      "description": "Date the Page was last modified"
-    }
-  },
-  "required": [
-    "id",
-    "name",
-    "html"
-  ],
-  "$schema": "http://json-schema.org/draft-04/schema#"
+  "message": "Page deleted successfully!",
+  "success": true,
+  "data": null
 }
    Response  404
    HideShow
    Headers
    Content-Type: application/json
    Body
    {
-    "message": "Group not found",
-    "success": false,
-    "data": null
-}
-{
-    "error": "Template not found"
+  "message": "Page not found",
+  "success": false,
+  "data": null
 }

    Import

    Import functions facilitate the ability to import emails, groups and more using simple interfaces.

    Group

    Import a Group
    POST/import/group

    This endpoint allows you to import a group from a CSV.

    The fields expected in the CSV are as follows:

    @@ -1554,7 +1316,7 @@ Content-Type: text/html; charset=UTF-8 } }, "$schema": "http://json-schema.org/draft-04/schema#" -}

    Generated by aglio on 26 Dec 2015

    -{{end}} +{{ end }} diff --git a/templates/gophish.apib b/templates/gophish.apib index c01afbb2..840c06d2 100644 --- a/templates/gophish.apib +++ b/templates/gophish.apib @@ -126,8 +126,8 @@ Campaigns have the following attributes: + ```name``` : Example Campaign (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](#users) -+ ```page``` : Attributes (Page) (required) - Landing page for users who click the phishing link ++ ```template``` : [Template](#templates) ++ ```page``` : [Page](#pages) (required) - Landing page for users who click the phishing link + ```status``` : Emails Sent (required, string) - The current status of the campaign + ```results``` : Attributes (ResultsList) + ```timeline``` : Attributes (EventList) @@ -190,7 +190,13 @@ Delete a campaign by its ID. + Response 200 (application/json) - + Attributes (Campaign) + + Body + + { + "message": "Page deleted successfully!", + "success": true, + "data": null + } + Response 404 (application/json) @@ -233,6 +239,14 @@ Get a list of templates. ### Create New Template [POST] Create a new template +::: note +## Importing an Existing Email + +What better way to make pixel-perfect emails than by importing an existing email you already have sitting in your inbox? + +Using the [Import Email](#import-email) endpoint, you can take a raw email and import it as a template into gophish. +::: + + Request (application/json) + Attributes (Template) @@ -276,7 +290,13 @@ Delete a template by its ID. + Response 200 (application/json) - + Attributes (Template) + + Body + + { + "message": "Template deleted successfully!", + "success": true, + "data": null + } + Response 404 (application/json) @@ -304,6 +324,13 @@ Each target contains the following attributes: + ```email```: john.doe@example.com - Email address of Target + ```position```: System Administrator - Company position of the Target +::: note +## Have A Lot of Users to Import? + +If you have all your targets in a CSV file, you can bulk import them into a group using the [Import CSV](#import-group) endpoint. + +In the future, we plan to add other importation methods to make setting up groups a breeze. +::: ## Groups [/groups/] ### Get Groups [GET] @@ -359,7 +386,13 @@ Delete a Group by its ID. + Response 200 (application/json) - + Attributes (Template) + + Body + + { + "message": "Group deleted successfully!", + "success": true, + "data": null + } + Response 404 (application/json) @@ -372,9 +405,6 @@ Delete a Group by its ID. } # Group Pages -Campaigns object contain the resources needed for gophish to launch and track a simulated phishing campaign. - -## Pages [/pages/] Pages are the HTML page that a user lands on after clicking on a phishing link. + ```id```: 1 (required, number) - Unique identifier @@ -382,8 +412,14 @@ Pages are the HTML page that a user lands on after clicking on a phishing link. + ```html```: `This is a test message!` (required, string) - HTML of the landing page users hit when clicking links in the email template + ```modified_date```: `2015-01-01T01:02:03.000000Z` (string) - Date the Page was last modified +::: note +## Importing a Site + +Let gophish do the hard work for you in importing a site. By using the [Import Site](#import-site) endpoint, you can simply give gophish a URL and have the site imported for you. +::: +## Pages [/pages/] ### Get Pages [GET] -Get a list of templates. +Get a list of pages. + Response 200 (application/json) @@ -442,7 +478,7 @@ Modify a page by its ID. + Body { - "message": "Group not found", + "message": "Page not found", "success": false, "data": null } @@ -456,20 +492,23 @@ Delete a page by its ID. + Response 200 (application/json) - + Attributes (Page) + + Body + + { + "message": "Page deleted successfully!", + "success": true, + "data": null + } + Response 404 (application/json) + Body { - "message": "Group not found", + "message": "Page not found", "success": false, "data": null } - { - "error": "Template not found" - } # Group Import Import functions facilitate the ability to import emails, groups and more using simple interfaces.