Extensible open source phishing incident response automation
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Martin 71e9a60410
Merge pull request #12 from maindefense/renovate/simple-java-mail.version
10 hours ago
.github Create FUNDING.yml 4 months ago
analyzers Fix copy-paste error in forward output configuration 3 weeks ago
common add possiblity to make output execution conditional 3 months ago
inputs [maven-release-plugin] prepare for next development iteration 3 months ago
outputs Fix copy-paste error in forward output configuration 3 weeks ago
phisherman Fix copy-paste error in forward output configuration 3 weeks ago
.gitignore add url analyzer 4 months ago
.travis.yml update to latest maen to fix build 3 months ago
LICENSE Update LICENSE 3 months ago
README.md Update README.md 3 months ago
SECURITY.md Update SECURITY.md 4 months ago
code-of-conduct.md add code of conduct 6 months ago
eclipse-java-google-style.xml Add initial project skeleton. 4 months ago
intellij-java-google-style.xml Add initial project skeleton. 4 months ago
pom.xml Update dependency org.simplejavamail:simple-java-mail to v5.4.0 2 days ago
renovate.json Add renovate.json 3 months ago
sonar-project.properties add initial analyzer 4 months ago

README.md

Build Status Contributors Apache-2.0 Vulnerabilities Quality Gate Status CII Best Practices


<img src="https://martinspielmann.de/phisherman.png" alt="Logo">

phisherman

Extensible open source phishing incident response automation
<br />
<a href="https://github.com/maindefense/phisherman/issues">Report Bug</a>
·
<a href="https://github.com/maindefense/phisherman/issues">Request Feature</a>

Table of Contents

About The Project

There are many phishing solutions out there, however, I didn’t find one that really suit my needs so I created this one. With phisherman users can forward suspicious mails to a configured mailbox. After an automated analysis they will get a response if the mail is malicilous or not. No manual action of helpdesk or security analysts needed.

Here’s why:

  • Your well trained users who report suspicious mails should get feedback quickly
  • Your support should be focused on creating an amazing customer experience instead of looking at phishing mails
  • You should have the flexibility to add custom inputs, analyzers and outputs as you like to seamlessly integrate with your existing environment
  • You should be able to have that for free and open source also in a commercial context

Of course, no solution will fulfill all requirements since your needs may be different from mine. So I’ll be adding more features in the near future. You may also suggest changes by forking this repo and creating a pull request or opening an issue.

Built With

phiherman is a String Boot application built with maven. It requires JDK 11 or later to work properly.

Getting Started

phisherman needs Java 11 to run, so first of all, you will have to install java on the machine that runs phisherman as described below.

Prerequisites

Install Java on your system

  • Java: Ubuntu sh sudo apt install default-jdk
  • Java: Fedora sh sudo dnf install java-11-openjdk
  • Java: Windows Install Java 11: E.g. OpenJDK or Oracle JDK

Usage

To start using phisherman, just download the latest version from the Releases and run the application with:

java -jar YOUR_DOWNLOADED_JAR

Configuration

Configuration is done via an application.yml file or the respective environment variables. Please refer to the file phisherman/src/main/resources/application-sample.yml for details:

common:
   thresholds:
      unsure: 50
      malicious: 100
input.imap:
   servers:
   -  hostname: 
      port: 
      username: 
      password: 
      folder: INBOX
      allowedSenders:
      - null
      
analyzer:
   header:
      whitelist:
         domains: null
         header-name: null
         header-values: null
      regex:
      -  header-name: name
         description: A brief description
         pattern: pattern
         weight: 10
         order: 1
      compare:
      -  header-name1: name1
         header-name2: name2
         description: Analyzer hits when name1 and name2 not equal
         operator: NOT_EQUALS
         weight: 10
         order: 2
   body:
      regex:
      -  pattern: pattern
         weight: 10
         order: 3
      url:
         obfuscated:
            weight: 10
            order: 4
         phishai:
           api-key: FOOBAR
           weight: 10
           order: 5
         openphish:
            api-key: FOOBAR
            weight: 10
            order: 6
output.smtp:
   answer:
      order: 100
      skip-upcoming: true
      hostname: 
      port:
      username:
      password:
      from-address: 
      subject-prefix: '[Phisherman] '
      answer-text-clean: Email is clean.
      answer-text-unsure: We are not sure.
      answer-text-malicious: Email is malicious.
      answer-template: |-
         <p>Thanks a lot for your report. Your email has been analyzed.</p>
         <p th:text="${answerText}"></p>
         <p>Total threat score: <span th:style="'color: ' + ${colorTotal}" th:text="${resultTotal}"></span></p>
         <p>Threat score by analyer:</p>
         <table style="border:1px solid #000">
         <thead>
         <tr>
         <th>Analyzer</th>
         <th>Threat Score</th>
         </tr>
         </thead>
         <tbody>
         <tr th:each="res : ${analyzerResults}">
         <td style="border:1px solid #000" th:text="${res.analyzerName}"></td>
         <td style="border:1px solid #000" th:text="${res.result}"></td>
         </tr>
         </tbody>
         </table>
      whitelist-answer-template: |-
         <p>Thanks a lot for your report. E-Mail has been whitelisted.</p>

Contributing

If you have any problem or idea, dont hesitate to report a bug or request a feature.

If ou want to help out with some code, tests or documentation, just follow these steps:

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature)
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

Any contributions you make are greatly appreciated. Please see the code-of-conduct.md before you start.

This project uses the Google Code Style. Please configure your IDE to use this formatting before you commit. For Eclipse and IntelliJ the required configuration files can be found in the root of the project repository (eclipse-java-google-style.xml, intellij-java-google-style.xml). Additionally, static code analysis is running on every build commit. Acceptable contributions should meet the requirements of the configured Quality Gate

Prepare

Install maven on your developer system

  • Java and Apache Maven: Ubuntu sh sudo apt install maven
  • Java and Apache Maven: Fedora sh sudo dnf install maven
  • Java and Apache Maven: Windows

Run

  1. Clone the repo sh git clone https://github.com/maindefense/phisherman.git
  2. Build maven packages sh mvn package
  3. Run the application sh mvn spring-boot:run

Versioning

This project uses Semantic Versioning

License

Distributed under the Apache License Version 2.0. See LICENSE for more information.

Dependencies should also be FLOSS and licenses should be approved by the open source initialtive. An automated report is created on every build and can manually created with the following command.

mvn license:third-party-report

Contact

Martin Spielmann - @pingunaut

Project Link: https://github.com/maindefense/phisherman

Acknowledgements