Merge pull request #3 from bjb28/json-references-improvements

README JSON reference improvement

README.md

@@ -44,6 +44,88 @@ docker build -t pca-assessment .
 We welcome contributions!  Please see [here](CONTRIBUTING.md) for
 details.
 
+## Assessment JSON Field Dictionary ##
+
+The following items are included in the assessment JSON as produced by the `pca-wizard`.
+An example assessment JSON can be found [here](src/assessment/sample_assessment.json).
+
+| Name | Description | Type | Default | Required |
+|------|-------------|:----:|:-------:|:--------:|
+| id | Assessment identifier. (e.g. "RV0000") | string | | yes |
+| timezone | Timezone name based on [pytz](http://pytz.sourceforge.net/) timezones. (e.g. "US/Eastern") | string | | yes |
+| domain | Assessment domain for GoPhish public interface. (e.g. "domain.tld") | string | | yes |
+| target_domain | Approved target domains where all email recipients must reside. (e.g. ["target1.tld", "target2.tld"]) | list(string) | | yes |
+| start_date | Assessment start date in 24-hr ISO format with offset. (e.g. "2020-01-01T14:00:00-04:00") | string | | yes |
+| end_date | Assessment end date in 24-hr ISO format with offset. (e.g. "2020-01-06T15:30:00-04:00") | string | | yes |
+| reschedule | Indicates if the assessment json is a rescheduled assessment. | boolean | | yes |
+| start_campaign | The campaign that the assessment should start at. | integer | `1` | no |
+| groups | Consolidated list of email recipients grouped to receive campaigns, [example](#group-dictionary). | list(dict) | | yes |
+| pages | GoPhish landing pages, [example](#page-dictionary). | list(dict) | | yes |
+| campaigns | Assessment campaigns, [example](#campaign-dictionary). | list(dict) | | yes |
+
+### Group Dictionary ###
+
+Groups are imported from a templated `csv` file that can be generated
+with the command `pca-wizard-templates  --targets`.
+
+| Name | Description | Type | Default | Required |
+|------|-------------|:----:|:-------:|:--------:|
+| name | Group name in the format of `{assessment identifier}-G{integer}` (e.g. "RV0000-G1"). | string | | yes |
+| targets | List of email recipients, [example](#target-dictionary). | list(dict) | | yes |
+
+### Target Dictionary ###
+
+| Name | Description | Type | Default | Required |
+|------|-------------|:----:|:-------:|:--------:|
+| first_name | Recipient's first name. | string | | yes |
+| last_name | Recipient's last name. | string | | yes |
+| email | Recipient's email address. (e.g. "john.doe@target1.tld") | string | | yes |
+| position | Position name for use in creating sub-groups of recipients within the organization such as "HR", "IT", etc. | string | | no |
+
+### Page Dictionary ###
+
+| Name | Description | Type | Default | Required |
+|------|-------------|:----:|:-------:|:--------:|
+| name | Page name in the format of `{assessment identifier}-{integer}-{descriptor}` (e.g. "RV0000-1-AutoForward"). | string | | yes |
+| capture_credentials | Capture all non-password input with GoPhish. Supports forwarding after submit action. | boolean | | yes |
+| capture_passwords | Capture password input by the user, but note that captured input is **stored in plain text as of GoPhish version 0.9.0.** | boolean | `False` | no |
+| html | Content of the landing page in HTML format. | string | | yes |
+
+### Campaign Dictionary ###
+
+| Name | Description | Type | Default | Required |
+|------|-------------|:----:|:-------:|:--------:|
+| name | Campaign name in the format of `{assessment identifier}-C{integer}` (e.g. "RV0000-C1"). | string | | yes |
+| launch_date | Campaign launch date in 24-hr ISO format with offset. (e.g. "2020-01-01T14:00:00-04:00")  | string | | yes |
+| completed_date | Campaign completion date in 24-hr ISO format with offset. (e.g. "2020-01-01T15:30:00-04:00")  | string | | yes |
+| url | Full URL for the campaign's landing page. (e.g. "http://domain.tld/camp/1") | string | | yes |
+| page_name | Landing page name as defined in the assessment json. | string | | yes |
+| group_name | Group name as defined in the assessment json. | string | | yes |
+| template | Email template for the campaign, [example](#email-template-dictionary). | dict | | yes |
+| smtp | GoPhish sending profile, [example](#smtp-dictionary). | dict | | yes |
+
+### Email Template Dictionary ###
+
+Email templates can be imported from a templated `json` file that can be be generated
+with the command `pca-wizard-templates  --emails`.
+
+| Name | Description | Type | Default | Required |
+|------|-------------|:----:|:-------:|:--------:|
+| name | Template name in the format of `{assessment identifier}-T{integer}-{template identifier}` (e.g. "RV0000-T1-1A2B3D"). | string | | yes |
+| subject | Email subject as seen by recipients. | string | | yes |
+| html | HTML representation of the email. | string | | yes |
+| text | Plain text representation of the email. | string | | yes |
+
+### SMTP Dictionary ###
+
+| Name | Description | Type | Default | Required |
+|------|-------------|:----:|:-------:|:--------:|
+| name | Sending profile name in the format of `{assessment identifier}-SP-{integer}` (e.g. "RV0000-SP-1"). | string | | yes |
+| from_address | From email address with display name, required format: `{display name}<{sending email address}>`. (e.g. "John Doe\<john.doe@domain.tld\>") | string | | yes |
+| host | Email server for GoPhish to send email through. | string | "postfix:587" | no |
+| interface_type | Type of interface GoPhish will use with mail server. | string | "SMTP" | no |
+| ignore_cert | Indicate if GoPhish should ignore certs with mail server. | boolean | `True` | no |
+
 ## License ##
 
 This project is in the worldwide [public domain](LICENSE).