Skip to content

Getting Started

Jump to bottom
be0vlk edited this page Aug 2, 2025 · 1 revision

Getting Started with Owlculus

Welcome to Owlculus, a comprehensive OSINT case management platform designed for solo investigators and teams. This guide will walk you through installation and creating your first case.

Prerequisites

Before installing Owlculus, ensure you have the following installed on your system:

  • Docker
  • Docker Compose
  • Git (for cloning the repository)
  • A modern web browser (Chrome, Firefox, Edge, or Safari)

Note: Owlculus has been tested exclusively on Linux. Windows users should use WSL (Windows Subsystem for Linux) to take advantage of the setup automation.

Installation

Step 1: Clone the Repository

git clone https://github.com/be0vlk/owlculus.git
cd owlculus

Step 2: Run the Setup Script

Make the setup script executable and run it:

chmod +x setup.sh
./setup.sh

Setup Options

The setup script offers several options:

  • Interactive Setup (default): ./setup.sh

    • You'll be prompted to choose between:
      • Local Development - For developers contributing to Owlculus
      • Local Production - For personal use or small teams
      • Remote Production - For deployment on a remote server

  • Clean Installation: ./setup.sh --clean

    • Removes any existing Docker containers and volumes before setup

  • With Test Data: ./setup.sh --testdata

    • Populates the database with sample data for testing

    • Creates test users with different roles:

      • analyst / anapassword1 (Analyst role)
      • investigator / invpassword1 (Investigator role)

    • Note that this can be (and probably should) be combined with the --clean flag for dev purposes.

Step 3: Initial Configuration

During interactive setup, you'll be asked to provide:

  1. Deployment Type - Choose "Local Production" for most users
  2. Admin Credentials:
    • Username
    • Email address
    • Password (auto-generated if not provided)

Important: Save your admin credentials! They'll be displayed at the end of setup. If you don't save them, you'll have to run the setup again.

Step 4: Access Owlculus

Once setup is complete, access Owlculus at:

Creating Your First Case

Step 1: Login

  1. Navigate to http://localhost:8081
  2. Login using the admin credentials from setup
  3. You'll be directed to the main dashboard

Step 2: Create a New Case

  1. Click the "New Case" or "Create First Case" button on the dashboard
  2. Fill in the case details:
    • Title: Descriptive name for your investigation (not the case number)
    • Client: The default "Personal" option is what it sounds like, for work that isn't associated with a client
    • Assign Users: If you are collaborating with others, you can add them to the case here and optionally set them as lead, which gives them the ability to create and assign tasks to other users. You can add and remove users later as well.
  3. Click "Create Case" to save
image

Step 3: Access Your Case

  1. Find your new case in the cases table on the dashboard
  2. Click on the case row to open it
  3. You'll see basic info and tabs for different case components:
    • Case Information: Case summary and details
    • Entities: People, companies, domains etc. tracked in the case
    • Evidence: Files and documents related to the case
    • Tasks: To-do items and assignments
    • Hunts: Run and/or view results from previous hunts
    • Notes: General case notes and observations
image

Step 4: Add Your First Entity

Entities are the core subjects of your investigation. To add one:

  1. Navigate to the Entities tab in your case
  2. Click "Add Entity"
  3. Choose the entity type:
    • Person: Individual subjects
    • Company: Organizations or businesses
    • Domain: Websites or online properties
    • IP Address: Network addresses
    • Vehicle: Cars, boats, aircraft
  4. Fill in the relevant information
  5. Each entity comes with a predefined template for notes and a dedicated free-form notes section just like the general case notes
image

Step 5: Upload Evidence

  1. Go to the Evidence tab
  2. Choose a folder structure:
    • Use pre-defined templates for common evidence types
    • Create custom folders for specific needs
  3. Click "Upload Evidence" or drag files into the upload area
  4. Right-click on evidence items for additional options:
    • Preview files
    • Delete items
    • Extract metadata using Exiftool
    • Copy the file hash
  5. You can easily click and drag evidence to other folders as needed and download the files to your local system with the download button on the right
image

Step 6: Run Your First OSINT Plugin or Hunt

  1. Navigate to the Plugins page from the main menu
  2. Browse available OSINT tools
  3. Select a plugin
  4. Enter required parameters
  5. Click "Run Plugin"
  6. Option to save results directly to case evidence
  7. For automated flows of common tasks like domain enumeration, check out the Hunts tab!
image image

Next Steps

Install the Browser Extension

Capture web pages directly to your cases as you browse:

  1. Navigate to the extension/ directory in the Owlculus repo
  2. Load the unpacked extension in Chrome developer mode
  3. Click the extension icon while browsing to capture pages

User Management

As an admin, you can create additional users directly:

  1. Go to Admin → User Management
  2. Create users with different roles:
    • Admin: Full system access
    • Investigator: Read/write access to assigned cases
    • Analyst: Read-only access to assigned cases
  3. You can also generate one-time invite links to allow users to setup their user themselves. They will be locked to whatever role you assign
image

Useful Commands

Updating Owlculus

To get the latest updates:

cd owlculus
git pull
docker compose down
docker compose up -d

Troubleshooting

Common Issues

Cannot access Owlculus after installation

  • Ensure Docker services are running: docker ps
  • Check logs: make logs
  • Make sure you are trying to access the correct host and port

Getting Help

  • GitHub Issues: Report bugs. Make sure to include logs when possible
  • GitHub Discussions: Request features and give general feedback
  • Documentation: Check the full documentation here in the wiki

Security Considerations

  • Use HTTPS for production deployments
  • Regularly backup your database
  • Keep the app updated
  • Never deploy the "dev" branch to production

Clone this wiki locally