System Architecture

Architectural Overview

Pulsar is designed as a modular, distributed network scanning platform. It follows a decoupled architecture consisting of a Vue.js frontend, a Django REST Framework (DRF) backend, and a background task engine powered by Celery. The system is built to handle recursive discovery of organizational assets while maintaining strict access control and providing rich data visualization.

Core Components

1. Frontend Layer (Vue.js)

The Pulsar dashboard is a Single Page Application (SPA) built with Vue.js 2.6.11 and Vue Router. It serves as the primary interface for:

• Scan Management: Configuring scan policies, scheduling tasks, and defining target scopes.
• Data Visualization: Interactive graphical representations of discovered infrastructure, mapping relationships between TLDs, subdomains, and IP addresses.
• Real-time Feedback: Monitoring active scan progress and system notifications.

2. Backend Layer (Django REST Framework)

The backend acts as the central orchestrator and API provider. It manages:

• Authentication & RBAC: Security is enforced via Django's LoginRequiredMixin and custom BaseViewSet logic. Data visibility is restricted based on object ownership or membership in collaboration groups.
• Business Logic: Processing scan results, calculating vulnerability scores (utilizing NVD data feeds), and managing the lifecycle of discovered assets.
• API Exposure: A RESTful API provides endpoints for external integrations and automation.

3. Background Engine (Celery & Scanning Modules)

To ensure high availability and responsiveness, all scanning operations are executed asynchronously.

• Celery Workers: Handle long-running tasks such as subdomain enumeration and port scanning.
• Scanner Extensions: A plug-and-play architecture for integrated tools (e.g., Nmap, Amass, CloudEnum). Pulsar executes these tools in a sandbox environment and parses their output back into the primary database.

Data Model & Storage

Pulsar utilizes a MySQL/MariaDB database (db_storage) with a hierarchical schema designed for asset traceability.

Asset Hierarchy

The data is structured to reflect the natural hierarchy of network infrastructure:

1. AssetInstance: The top-level organizational entity (e.g., "Company X").
2. DomainInstance: Subdomains and TLDs associated with the asset.
3. IPv4AddrInstance: Specific network interfaces and IP addresses linked to domains.
4. Vulnerability/Service Data: Metadata attached to IPs and domains reflecting scan results.

Access Control Logic

Data access is programmatically filtered at the database level. When a user requests data, the system applies the following filter:

# Simplified internal logic for asset filtering
assets = AssetInstance.objects.filter(
    Q(owner=user) | Q(collaborations__in=user.groups.all())
)

Data Visualization Layer

Pulsar transforms raw scan data into actionable intelligence through its visualization layer.

• Relational Mapping: The UI maps the relationship between discovered cloud resources and public-facing infrastructure.
• Vulnerability Scoring: Based on the NVD (National Vulnerability Database) feed, Pulsar assigns a basic score to discovered assets to highlight weak points.
• Export Capabilities: Data can be exported for collaboration or integrated into other reporting tools.

REST API Interface

Pulsar provides a comprehensive REST API for programmatic interaction. Authentication can be handled via Basic Auth, Session, or Token-based methods.

Endpoint Usage Example

Retrieve Discovered Domains

• Endpoint: /api/domains/
• Method: GET
• Parameters:
  • asset: (Integer) Filter by Asset ID.
  • search: (String) Search by domain name.

Request:

curl -X GET http://pulsar-instance/api/domains/ \
     -H "Authorization: Token <your_token>"

Response:

[
  {
    "id": 101,
    "name": "api.example.com",
    "asset": 5,
    "ipv4_addresses": ["192.168.1.1"],
    "vulnerabilities_count": 2,
    "last_seen": "2023-10-27T10:00:00Z"
  }
]

External API Integration

While Pulsar is designed to function without required API keys, it supports optional integrations with external services (like RIPEstat) to enrich discovered data. These are configured via the USAGE.md guidelines in the portal settings.