# crownss/pulsar-star architecture

> Architecture diagram of the GitHub repository crownss/pulsar-star, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/crownss/pulsar-star
- Repository: https://github.com/crownss/pulsar-star

## Overview

pulsar-star is a Linux layer-2 ARP cache-poisoning tool. The documented workflow parses options, discovers subnet hosts with nmap, selects targets and an interface, then starts a CPU-pinned sender that repeatedly broadcasts forged ARP replies through a raw datalink channel. The graph separates discovery and target preparation from packet transmission, and includes the main-thread progress display. The README documents the overall stages; the sampled source confirms the sender and packet-building calls. All implementation responsibilities reside in src/main.rs.

Main entry points: [`src/main.rs`](https://github.com/crownss/pulsar-star/blob/main/src/main.rs) (Sender thread)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Discovery and targeting"]
  node_host_discovery["Host discovery<br/>[main.rs]"]
  node_target_filter["Target filtering<br/>[main.rs]"]
  node_interface["Interface selection<br/>[main.rs]"]
end

subgraph group_transmission["ARP transmission"]
  node_sender["Sender thread<br/>[main.rs]"]
  node_affinity["CPU affinity<br/>[main.rs]"]
  node_channel["Datalink channel<br/>[main.rs]"]
  node_poison_loop["Poison loop<br/>[main.rs]"]
  node_arp_builders["ARP reply builders<br/>[main.rs]"]
end

subgraph group_runtime["Runtime coordination"]
  node_cli["CLI options<br/>[main.rs]"]
  node_main_flow["Main workflow<br/>[main.rs]"]
  node_progress["Progress display<br/>[main.rs]"]
end

node_operator(("Operator"))
node_nmap["nmap scanner"]
node_lan(("LAN hosts"))

node_operator -->|"provides options"| node_cli
node_cli -->|"configures scan"| node_host_discovery
node_host_discovery -->|"runs scan"| node_nmap
node_nmap -->|"reports hosts"| node_host_discovery
node_host_discovery -->|"returns hosts"| node_target_filter
node_target_filter -->|"sets targets"| node_main_flow
node_main_flow -->|"uses interface"| node_interface
node_main_flow -->|"starts sender"| node_sender
node_sender -->|"pins thread"| node_affinity
node_sender -->|"opens channel"| node_channel
node_sender -->|"uses interface"| node_interface
node_sender -->|"runs loop"| node_poison_loop
node_poison_loop -->|"builds replies"| node_arp_builders
node_arp_builders -->|"sends frames"| node_channel
node_channel -->|"broadcasts frames"| node_lan
node_main_flow -->|"prints progress"| node_progress

click node_cli "https://github.com/crownss/pulsar-star/blob/main/src/main.rs"
click node_host_discovery "https://github.com/crownss/pulsar-star/blob/main/src/main.rs"
click node_target_filter "https://github.com/crownss/pulsar-star/blob/main/src/main.rs"
click node_interface "https://github.com/crownss/pulsar-star/blob/main/src/main.rs"
click node_main_flow "https://github.com/crownss/pulsar-star/blob/main/src/main.rs"
click node_sender "https://github.com/crownss/pulsar-star/blob/main/src/main.rs"
click node_affinity "https://github.com/crownss/pulsar-star/blob/main/src/main.rs"
click node_channel "https://github.com/crownss/pulsar-star/blob/main/src/main.rs"
click node_poison_loop "https://github.com/crownss/pulsar-star/blob/main/src/main.rs"
click node_arp_builders "https://github.com/crownss/pulsar-star/blob/main/src/main.rs"
click node_progress "https://github.com/crownss/pulsar-star/blob/main/src/main.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_host_discovery,node_target_filter,node_interface toneBlue
class node_sender,node_affinity,node_channel,node_poison_loop,node_arp_builders toneAmber
class node_cli,node_main_flow,node_progress toneMint
class node_operator,node_nmap,node_lan toneIndigo
```

## Components

### Discovery and targeting

- [Host discovery](https://github.com/crownss/pulsar-star/blob/main/src/main.rs): `src/main.rs`
- [Target filtering](https://github.com/crownss/pulsar-star/blob/main/src/main.rs): `src/main.rs`
- [Interface selection](https://github.com/crownss/pulsar-star/blob/main/src/main.rs): `src/main.rs`

### ARP transmission

- [Sender thread](https://github.com/crownss/pulsar-star/blob/main/src/main.rs): `src/main.rs`
- [CPU affinity](https://github.com/crownss/pulsar-star/blob/main/src/main.rs): `src/main.rs`
- [Datalink channel](https://github.com/crownss/pulsar-star/blob/main/src/main.rs): `src/main.rs`
- [Poison loop](https://github.com/crownss/pulsar-star/blob/main/src/main.rs): `src/main.rs`
- [ARP reply builders](https://github.com/crownss/pulsar-star/blob/main/src/main.rs): `src/main.rs`

### Runtime coordination

- [CLI options](https://github.com/crownss/pulsar-star/blob/main/src/main.rs): `src/main.rs`
- [Main workflow](https://github.com/crownss/pulsar-star/blob/main/src/main.rs): `src/main.rs`
- [Progress display](https://github.com/crownss/pulsar-star/blob/main/src/main.rs): `src/main.rs`

### Other components

- **Operator**
- **nmap scanner**
- **LAN hosts**

## Connections

- Operator → CLI options: provides options (evidence: `README.md`)
- CLI options → Host discovery: configures scan (evidence: `README.md`)
- Host discovery → nmap scanner: runs scan (evidence: `README.md`)
- nmap scanner → Host discovery: reports hosts (evidence: `README.md`)
- Host discovery → Target filtering: returns hosts (evidence: `README.md`)
- Target filtering → Main workflow: sets targets (evidence: `src/main.rs`)
- Main workflow → Interface selection: uses interface (evidence: `README.md`)
- Main workflow → Sender thread: starts sender (evidence: `src/main.rs`)
- Sender thread → CPU affinity: pins thread (evidence: `src/main.rs`)
- Sender thread → Datalink channel: opens channel (evidence: `src/main.rs`)
- Sender thread → Interface selection: uses interface (evidence: `src/main.rs`)
- Sender thread → Poison loop: runs loop (evidence: `src/main.rs`)
- Poison loop → ARP reply builders: builds replies (evidence: `src/main.rs`)
- ARP reply builders → Datalink channel: sends frames (evidence: `src/main.rs`)
- Datalink channel → LAN hosts: broadcasts frames (evidence: `README.md`)
- Main workflow → Progress display: prints progress (evidence: `src/main.rs`)
