PHISHCASE / Documentation

PhishCase documentation

Receiving a message, qualifying evidence or coordinating a team? Start with your task, then keep the evidence, decision and next step together.

In the application: authorized users can read; analysts and administrators can write. PhishCase accounts and data remain independent of SafeScan.

What do you need to do?

Overview

PhishCase turns a suspicious message into a traceable investigation: preserved original, human qualification, explained correlations and tracked next actions. Reading a campaign, analyzing email and coordinating a team each have their own path. Community is self-hosted; Cloud adds accounts, organizations and governance. PhishCase accounts remain independent of SafeScan accounts. Public commercial signup remains closed while the service is prepared.

Upload a new message

Start in Reception and upload an EML/MSG. Each email is saved directly with its original and analysis. Campaigns are optional. Upload requires an analyst or administrator role.

  1. Select an original EML or MSG, or several files: up to 20 files of 20 MB each. Keep the reporting context separately.
  2. Upload the files. The receipt confirms intake; the worker continues processing if you close the browser.
  3. Open the received message or find it in Emails. Select relevant messages to create a campaign or link them to an existing campaign.
  4. If processing fails, read the reason before an explicit retry. Do not upload another copy merely because processing is still running.
At the end

The original, its hash and the analysis identifier are preserved. An automated result is not yet a human decision.

Technical guide in the repository ↗

Independent emails

Emails stores uploaded messages, including those without a campaign. Each message has its original, attachments, analysis, verdict and reporter replies. Select one or more emails to create a campaign or link them to an existing one. An email can belong to several campaigns; unlinking it preserves its evidence and verdict.

Technical guide in the repository ↗

Qualify the message

Open the analysis to read the neutralized original beside results and the human decision. The body executes no HTML and loads no remote resource. Evidence, IoC/correlations and technical details remain accessible in their tabs; follow-up groups next actions and the reporter reply.

Cryptographic DKIM verification is a separate action. An administrator must enable DKIM_LOOKUP_ENABLED in Community, or the organization’s DKIM permission in Cloud, in a mode allowing lookups. The button explains that selector and domain names go to the DNS resolver; the message stays local. Results distinguish valid, invalid, unsigned and unavailable verification without changing your verdict.

  1. Read the message and compare sender, Reply-To, displayed links and extracted destination. Inspect attachment metadata and hashes without executing attachments.
  2. Review headers, the Received route and local observations. Received SPF/DKIM/DMARC results are assertions, not an independent verification.
  3. Choose from eight verdicts: legitimate, spam, phishing, credential phishing, malware delivery, BEC fraud, suspicious or inconclusive.
  4. Add your confidence and an evidence-based justification, then save the decision.
  5. To revise a conclusion, reopen the decision and read its history. Export JSON, an HTML report or an evidence package as needed.
At the end

The analyst decision remains distinct from automated results. Its author and versions are retained; a new concurrent decision requires history to be reloaded.

Technical guide in the repository ↗

Work with other analysts

Campaigns separates My campaigns and Team. Assignment identifies who leads an investigation; it does not make the campaign private or divide access within a team. Cloud organizations remain separate.

  1. Open My campaigns to resume your work, or Team to find a shared investigation.
  2. Assign the campaign to an active analyst and preserve context in notes and history. Divide next steps into named actions.
  3. If a colleague changes a campaign, action, draft or intelligence record while you read it, reload the requested version before revising your change.
  4. For concurrent decisions, read the new history before deciding or reopening. A stale version is rejected instead of overwriting saved work.
At the end

The responsible analyst, decisions and changes remain traceable. Campaigns are never merged automatically.

Technical guide in the repository ↗

IoC and correlation

IoC provides extracted URLs, domains, IP addresses and hashes, their occurrences and original emails. Similarity reasons explain shared domains, URLs, hashes, senders or subjects. Check the original, then document your interpretation in a campaign. A match proves neither maliciousness nor attribution; no automatic grouping is performed.

Campaigns

A campaign groups emails for a collective investigation. It holds its name, description, tags, owner, priority, status, notes, actions and history. My campaigns and Team organize the work. Link emails after reviewing similarities and inspect their IoC and individual verdicts. Unlinking an email removes only the relationship. Updates require the version read to preserve other analysts’ work.

Technical guide in the repository ↗

Document a possible link

From a campaign, or Explore → Intelligence, document a possible connection with a leak or known campaign. Record sources, facts, limitations, hypotheses and your confidence. References remain text and trigger no external fetch.

  1. Record a source reference and observation date. References remain text; entering one triggers no remote resource loading.
  2. Describe observed facts, followed by counter-evidence that could contradict the relationship.
  3. State the hypothesis and your confidence from 0 to 100. This is your judgment, not a calculated score or proof of a match.
  4. Link the relevant campaign, save and review the record when new evidence appears.
At the end

The hypothesis has readable sources, facts and counter-evidence. IoC matches remain distinct observations.

Technical guide in the repository ↗

Track next actions

Add actions in the campaign follow-up, or open Actions to find them across the workspace. They turn a conclusion into tracked work: check access, preserve evidence or contact someone.

  1. Give the action a precise title, select its responsible person from active users and set a due date when known.
  2. Save its state: to do, in progress, done or cancelled. The list and campaign refer to the same record.
  3. To complete it, document the evidence or result. To cancel it, record the reason; this information is required.
  4. Reopen a closed campaign before creating or changing an action. Reload if someone has saved a newer version.
At the end

An action retains its assignee, due date, state and result. To-do and in-progress actions prevent campaign closure.

Technical guide in the repository ↗

Reply to the reporter

Prepare the reporter response in analysis or campaign follow-up. Enter their address explicitly: the suspicious message sender is never automatically selected as recipient. Drafting remains possible without a mail transport.

In Community, administrators configure SMTP_HOST and SMTP_FROM, then SMTP_PORT and SMTP_USERNAME/SMTP_PASSWORD when needed. STARTTLS is the default; SMTP_SSL=true selects implicit TLS. Cloud reuses its configured SMTP or Mailgun transport. Indicator lookup policy does not configure reporter reply delivery.

  1. If the reply belongs to an analysis, first save an active analyst decision.
  2. Enter the recipient, subject and draft. Choose Create draft and preview, or Save and preview for an edit.
  3. Read the address and text in the preview. HTML-looking strings remain plain text.
  4. When transport is configured, choose Send this response to transmit exactly the previewed version. This step is always explicit.
At the end

Accepted means accepted by the transport, with no proof of delivery or reading. An accepted response cannot be edited or resent.

Technical guide in the repository ↗

Resolve an interrupted send

A timeout can leave an uncertain result; a service interruption can leave a reply sending. No automatic retry occurs. Reconcile the outcome against transport logs before deciding what to do next.

  1. Open the reply and choose Reconcile transmission result. This operation requires an analyst or administrator role.
  2. Check SMTP or Mailgun logs and select confirmed acceptance, or confirmed failure without acceptance. Do not infer failure merely from an empty recipient inbox.
  3. Enter the evidence or reference and save the verified outcome. Operator, time, proof and revision are retained.
  4. After a verified failure, you may edit the draft, preview it and explicitly send it. Reconciliation itself sends nothing.
At the end

Verified acceptance unlocks closure without claiming delivery. Concurrent changes are rejected; a late result does not overwrite a recorded reconciliation.

Technical guide in the repository ↗

Close a completed investigation

Campaign status organizes work; it does not replace message processing results or analyst qualification. Closure checks tasks and messages still awaiting work.

  1. Check that processing has finished and every completed analysis has an active human decision.
  2. Finish or cancel outstanding actions with their result or reason.
  3. Reconcile replies still sending. Verified transport acceptance does not prove delivery.
  4. Save the closed status. If closure is refused, return to the indicated item and resolve it before trying again.
At the end

A campaign cannot close with a pending action, a processing message, an unqualified completed analysis or a sending reply. Reopen it to resume work.

Technical guide in the repository ↗

Getting started with Cloud

When signup is open, enter account details and an organization name, then confirm the emailed link. The trial includes 14 days and 30 analyses. The Cloud workspace manages members, integrations, billing and retention policy according to role and plan; webhooks and purge operations have an administrator API. The active organization determines visible data. Billing currently uses simulated tests; real payments and commercial signup remain closed.

Accounts and sessions

Use a unique password and enable MFA. Community starts with an administrator created in the terminal; Cloud uses email verification and invitations. Sessions use HttpOnly cookies; browser writes require CSRF protection. API tokens are personal, time limited and shown once. Credential resets revoke obsolete sessions. SSO/OIDC/SAML/LDAP remain planned; this version does not include a working identity-provider connection.

Profile provides My account and permitted administrator functions. Explorer groups overview, analyses, search and intelligence; the five primary entries remain Reception, Emails, IoC, Campaigns and Actions. Menus support the keyboard and close with Escape. Short task guides are optional and replayable.

Multi-factor authentication

In account settings, start TOTP setup, add the secret to your authenticator and confirm with a valid code. Store recovery codes separately; each works only once. Do not send them to support. The application encryption key must be included in a protected backup to recover MFA secrets. Losing both the phone and recovery codes requires an administered recovery procedure.

Roles and seats

A viewer reads accessible data without changing it. An analyst uploads messages and investigates them. An administrator manages members and configuration. In Cloud, administrators and analysts, including their pending invitations, consume the 3/10/25 seats; viewers do not. The SaaS operator console exposes operational metadata without automatically granting access to customer emails.

Enrichment and sharing

Initial parsing stays local in every mode. Trigger enrichment from an existing analysis after reviewing what will be sent. A lookup sends the selected indicator; a submission sends the chosen file or asks the provider to visit a URL. Missing results never cause automatic submission. Community reads keys from server secrets; Cloud uses organization-specific administrator settings, encrypted keys and separate permissions.

Technical guide in the repository ↗

VirusTotal

File lookup sends its SHA-256, not its bytes. URL, domain and IP lookups transmit those values. File/URL submissions require connected mode and a separate permission; pending results are polled explicitly. Unknown, harmless, suspicious and malicious counts remain separate. This integration uses the standard API, not Private Scanning. Check your license and permitted uses with the provider before commercial use.

Technical guide in the repository ↗

urlscan.io

Look up an existing scan or explicitly submit an extracted URL. Default visibility is private; a plan restriction never causes a silent fallback to public. Unlisted does not mean private. Results may include title, domain, IP, score and partial redirects. External screenshots and reports require an explicit action and may need provider authentication. PhishCase does not visit the suspicious page.

Technical guide in the repository ↗

Connectivity modes

Offline blocks external enrichment and optional DNS verification. Restricted permits authorized lookups only; connected also permits enabled submission types. A key never implies permission to send evidence. Previously stored results remain readable offline. For a network boundary independent of software policy, also configure a firewall/Docker networks. Cloud email authentication and billing services have separate operational connections.

Technical privacy

Emails may contain personal data and secrets. Restrict access, avoid unnecessary submissions and export only needed evidence. The public site has no analytics or third-party resources; it only stores language preference in the browser. The application maintains sessions needed for authentication. See the Privacy page for storage, recipients, retention and documents requiring review before commercial launch.

Read the dedicated page ↗

Retention and deletion

Cloud provides 90/180/365 days by plan, with shorter periods selectable by an administrator. This version requires a preview and explicit purge confirmation; no scheduler automatically erases evidence at expiry. Running analyses are excluded. Review selected items and resume cleanup marked pending. Campaigns, notes, audit, billing and backups have separate lifecycles; a local purge does not remove a previous provider submission.

Replies linked to an analysis are included in its retention scope. An active transmission blocks purge of the affected analysis; reconcile its outcome before resuming deletion.

Security and limitations

Originals are verified with SHA-256; downloads require authentication, use attachment disposition, no cache and no MIME sniffing. CPU/memory/time and MIME limits reduce parsing risks without forming a detonation sandbox. Files are not individually encrypted at rest: protect the host disk. The Security page explains boundaries and private reporting. Do not post confidential emails, secrets or exploit details in a public issue.

Technical guide in the repository ↗

Read the dedicated page ↗

Quick start

Clone the candidate branch, select the stated revision, copy the configuration and start Docker. There is no default account. The administrator creation command asks for details in the terminal. Then open http://127.0.0.1:8088, sign in and upload a small test EML. Preserve the data volume across restarts.

git clone --branch codex/pastel-identity-20261025 https://github.com/CybersecSpirit/phishcase.git
cd phishcase
git checkout 2d0d1c550dbf088391b1cf349e091c3ef1a61568
cp .env.example .env
docker compose up -d --build
docker compose ps
docker compose exec phishcase python -m backend.investigation.store

Community installation

Requirements: Git, Docker Engine and Docker Compose, persistent storage and enough resources for the container limits (2 GiB). Community works without provider keys. Keep CONNECTIVITY_MODE=offline for the first trial. All active members can read team evidence: assigning a campaign does not create an access boundary. Use separate instances or Cloud for separate organizations.

Technical guide in the repository ↗

Docker and persistence

The main Compose file runs the API, worker and local SpamAssassin. The service binds only to loopback; /data holds SQLite, evidence and the generated MFA key when none is supplied. Check docker compose ps and then /ready. docker compose down preserves volumes; -v destroys them and is never part of a normal upgrade. Retain the previous image for rollback.

Technical guide in the repository ↗

Production deployment

Put the application behind an HTTPS proxy, enable COOKIE_SECURE=true and allow 21 MiB requests for the 20 MiB file limit. Protect volumes and secret files. /health indicates a responsive server; /ready also checks the database, storage and recent worker presence. In Cloud, PostgreSQL stays on the internal Docker network. Before opening signup, verify email delivery, restoration, monitoring and service terms.

Plesk deployment

Plesk owns ports 80/443 and certificates. Create the site, docs and app subdomains, point DNS at the VPS and issue certificates before forcing HTTPS. Route their / locations to loopback ports 8086, 8087 and 8088. Preserve ACME handling, overwrite client forwarded headers and use a 60-second timeout. Do not edit generated vhosts or existing sites. The private PLESK.md guide provides exact directives and rollback checks.

Encrypted backup

Stop writers for a consistent operational snapshot. Community backs up SQLite and evidence; Cloud uses pg_dump with referenced evidence. The authenticated archive includes explicitly selected configuration and the MFA/application key. Keep the archive key separate. Agree a schedule and retention policy; the software does not install that schedule automatically. Keep an independent copy when its destination is authorized. A backup on the same VPS does not cover total server loss.

Technical guide in the repository ↗

Restore and verify

Restore only into an empty database and directory in an isolated stack. Check image version, keys and external destinations before starting the worker: restoration also returns queues and sessions to their saved state. Verify MFA login, an original hash, attachment, quota and organization boundaries. Require /ready before switching the proxy. Never overwrite production to test recovery.

Technical guide in the repository ↗

Upgrade

Select a reviewed revision, take a backup and record image and migration references. Build the new image. Community applies additive migrations at startup; Cloud explicitly runs alembic upgrade head before the API/worker. A migration failure blocks returning to service. Reverting the image is safe only when it supports the current schema; otherwise restore the prior snapshot into another stack and switch after verification.

The Emails/Campaigns model uses SQLite 2026101002, Cloud Alembic 20261010_0005 and tenant 20261010_tenant_0003. Automatic cases without context become independent emails. Useful context becomes a campaign, preserving owners, notes, actions, replies, relationships and history. Old links are archived and redirected. Stop writers, back up and verify restoration and migration on a copy before production. Returning to an older image requires a compatible backup.

Troubleshooting

503 on /ready: check PostgreSQL/SQLite, volume permissions and recent worker activity. Stalled analysis: inspect the job, wait for lease expiry after a stop, then explicitly retry if failed. 413: check file size and proxy limits. Provider 403: review mode, role and operation permission; do not enable submission to fix a lookup failure. Missing account email: check SMTP and the outbox without printing tokens. After changing secrets, recreate the affected service.

409 during an edit: reload the indicated record. Refused closure: finish actions, qualify analyses and check remaining transmissions. Unconfigured transport: retain the draft and ask for SMTP or Mailgun configuration. Uncertain send: reconcile with proof, without automatic retry.

API and ingestion

Create a token from an authorized account and store it in a secret manager. Community exposes /api/v1; Cloud exposes investigations under /api/workspace and accounts under /api/cloud. Send multipart file to /analyses; the 202 response provides an ID to poll until completed or failed. A stable Idempotency-Key deduplicates the same retried action. Use page/page_size pagination to avoid incomplete lists. See the Community API contract for 401/403/409/413/422/429 responses.

POST /analyses saves an independent email. POST /campaigns can accept analysis_ids; POST /campaigns/{id}/emails and DELETE /campaigns/{id}/emails/{analysis_id}?revision=… manage relationships. GET /analyses/{id}/campaigns exposes its campaigns. Return revisions for campaigns, memberships, actions, drafts and reconciliation; decisions use the last decision ID read. A 409 requires a refresh. The cases and campaign_cases tables remain for compatibility and historical traceability.

Technical guide in the repository ↗

Outgoing webhooks

Team/Business administrators configure up to five public HTTPS destinations. Analysis, verdict and campaign events contain identifiers and states, without email bodies or attachments. Save the secret shown once. Verify HMAC-SHA256 over timestamp + "." + the raw HTTP body, timestamp freshness and event ID uniqueness. The receiver must deduplicate because delivery may be repeated. Rotation immediately replaces the secret, including for pending retries.

Architecture

The core combines an API, persistent queue, worker, bounded parser and immutable evidence storage. Community uses SQLite. Cloud adds a PostgreSQL control plane and investigation schemas per organization, selected server-side from the authenticated identity. Isolation is application enforced with a shared PostgreSQL role; it is not separation by OS or database account. Redis, high availability and distributed object storage are not required for this single-host V1.

Technical guide in the repository ↗

Open-core architecture

Community is public under MIT and works independently. The private Enterprise repository references an exact core revision through a submodule, then builds its adapter and interfaces. Generic fixes remain public; provisioning, billing and SaaS operations remain private. The history and MIT notice of eml_analyzer/Manabu Niseki are preserved. Detaching the repository from the fork network removes neither ancestry nor attribution obligations.

Technical guide in the repository ↗

Enterprise and services

Enterprise On-Premise is available on request, subject to an agreed scope. Installation, migration, configuration, guidance, training, SIEM/SOAR integration and enhanced maintenance are services to scope with the publisher. SSO/LDAP, premium connectors and MSSP remain planned work, not active candidate features. Agree scope, commercial licensing and support before committing.

Development and testing

The core requires Python 3.14, Node 24, uv and libmagic. Install locked dependencies, build the frontend and run API and worker with matching data paths. Use synthetic fixtures and a separate database. Historical tests require SpamAssassin; Cloud tests require PostgreSQL 17. Stripe stays simulated without an account, or in test mode with your own account. Development, tests, staging and production must not share databases, volumes, keys or notification destinations.

Technical guide in the repository ↗

Contributing

Open a focused branch and pull request in Community for a generic improvement. Describe the problem, behavior and checks; preserve MIT notices and never add secrets or real customer email to fixtures. Follow CONTRIBUTING.md and SECURITY.md. Commercial extensions evolve in the private repository.

Technical guide in the repository ↗

Scope and roadmap

Scope includes EML/MSG upload and API, human qualification, correlations, teamwork, persistent actions, reporter replies with transport reconciliation and sourced hypotheses, alongside accounts/organizations and Docker operations. Inbound email, add-ins, SSO, MSSP, premium connectors and distributed architecture remain future work. Local checks do not replace verification of SMTP delivery, a Stripe test account or provider contractual permissions before commercial launch.