Skip to content

Commit 898dde6

Browse files
Copilotnpv2k1
Copilot
and
npv2k1
committed
Add comprehensive implementation documentation
Co-authored-by: npv2k1 <73846954+npv2k1@users.noreply.github.com>
1 parent d51243f commit 898dde6

1 file changed

Lines changed: 210 additions & 0 deletions

File tree

‎PORT_EXPLORER_IMPLEMENTATION.md‎

Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
# Port Explorer Implementation Summary
2+
3+
## Overview
4+
This document describes the implementation of the Port Explorer module for PNTools, which provides port scanning capabilities with both native TCP scanning and optional nmap integration.
5+
6+
## Architecture
7+
8+
### Backend (Rust/Tauri)
9+
Located in `src-tauri/src/`:
10+
11+
1. **modules/port_scanner.rs** - Core port scanning logic
12+
- Native TCP-based port scanning using Rust's standard library
13+
- Nmap integration for advanced scanning
14+
- Service name detection for common ports
15+
- Configurable timeout and port range support
16+
17+
2. **commands/port_scanner.rs** - Tauri command handlers
18+
- `scan_ports_command`: Main scanning function exposed to frontend
19+
- `check_nmap_available`: Check if nmap is installed on the system
20+
21+
### Frontend (React/TypeScript)
22+
Located in `src/modules/tauri/components/port-explorer/`:
23+
24+
1. **index.tsx** - Main React component
25+
- User interface for configuring and running port scans
26+
- Interactive results table with filtering and sorting
27+
- Real-time scanning status and progress
28+
- Error handling and nmap availability detection
29+
30+
## Features Implemented
31+
32+
### 1. Native Port Scanning
33+
- Uses Rust's `TcpStream::connect_timeout` for fast, reliable port checking
34+
- No external dependencies required
35+
- Cross-platform support (Windows, macOS, Linux)
36+
- Configurable timeout per port
37+
38+
### 2. Nmap Integration
39+
- Optional use of nmap for more advanced scanning
40+
- Automatic detection of nmap availability
41+
- Parses nmap output for enhanced service detection
42+
- Fallback to native scanning if nmap fails
43+
44+
### 3. Service Detection
45+
Common services automatically detected:
46+
- FTP (20, 21)
47+
- SSH (22)
48+
- Telnet (23)
49+
- SMTP (25)
50+
- DNS (53)
51+
- HTTP (80, 8080)
52+
- HTTPS (443, 8443)
53+
- SMB (445)
54+
- MySQL (3306)
55+
- RDP (3389)
56+
- PostgreSQL (5432)
57+
- VNC (5900)
58+
- Redis (6379)
59+
- MongoDB (27017)
60+
61+
### 4. User Interface
62+
- Clean, intuitive design using Ant Design components
63+
- Real-time scan progress indication
64+
- Results displayed in sortable, filterable table
65+
- Visual status indicators (green/red tags for open/closed ports)
66+
- Summary statistics showing open vs. scanned ports
67+
68+
## API Reference
69+
70+
### Rust Commands
71+
72+
#### `scan_ports_command`
73+
```rust
74+
fn scan_ports_command(
75+
host: String,
76+
start_port: u16,
77+
end_port: u16,
78+
use_nmap: bool,
79+
timeout_ms: u64,
80+
) -> Result<Vec<PortScanResult>, String>
81+
```
82+
83+
**Parameters:**
84+
- `host`: Target hostname or IP address
85+
- `start_port`: First port in range to scan (1-65535)
86+
- `end_port`: Last port in range to scan (1-65535)
87+
- `use_nmap`: If true, use nmap; if false, use native scanning
88+
- `timeout_ms`: Connection timeout in milliseconds
89+
90+
**Returns:** List of port scan results or error message
91+
92+
#### `check_nmap_available`
93+
```rust
94+
fn check_nmap_available() -> bool
95+
```
96+
97+
**Returns:** `true` if nmap is installed and accessible, `false` otherwise
98+
99+
### Data Structures
100+
101+
#### PortScanResult
102+
```rust
103+
struct PortScanResult {
104+
port: u16, // Port number
105+
is_open: bool, // Whether port is open
106+
service: Option<String>, // Detected service name
107+
}
108+
```
109+
110+
## Usage Example
111+
112+
### From the UI:
113+
1. Launch PNTools application
114+
2. Navigate to: **Tauri > PortExplorer**
115+
3. Configure scan parameters:
116+
- Host: `127.0.0.1` (or any IP/hostname)
117+
- Start Port: `1`
118+
- End Port: `1024`
119+
- Timeout: `1000` ms
120+
- Use nmap: Toggle on/off
121+
4. Click "Start Scan"
122+
5. View results in the table
123+
124+
### From Code (TypeScript):
125+
```typescript
126+
import { invoke } from '@tauri-apps/api/core';
127+
128+
// Scan ports 80-443 on localhost
129+
const results = await invoke('scan_ports_command', {
130+
host: '127.0.0.1',
131+
startPort: 80,
132+
endPort: 443,
133+
useNmap: false,
134+
timeoutMs: 1000,
135+
});
136+
137+
// Check if nmap is available
138+
const nmapAvailable = await invoke('check_nmap_available');
139+
```
140+
141+
## File Changes
142+
143+
### New Files Created:
144+
1. `src-tauri/src/modules/port_scanner.rs` - Port scanning logic
145+
2. `src-tauri/src/commands/port_scanner.rs` - Tauri command handlers
146+
3. `src/modules/tauri/components/port-explorer/index.tsx` - React UI component
147+
4. `src/modules/tauri/components/port-explorer/README.md` - Module documentation
148+
149+
### Modified Files:
150+
1. `src-tauri/src/modules/mod.rs` - Added port_scanner module
151+
2. `src-tauri/src/commands/mod.rs` - Added port_scanner commands
152+
3. `src-tauri/src/main.rs` - Registered new Tauri commands
153+
4. `src/modules/tauri/index.tsx` - Added PortExplorer route
154+
5. `README.md` - Added feature documentation
155+
156+
## Security Considerations
157+
158+
1. **Authorization**: Port scanning should only be performed on networks/systems you own or have explicit permission to scan
159+
2. **Rate Limiting**: Consider adding rate limiting for large port ranges to avoid overwhelming the target
160+
3. **Logging**: Scans are not logged by default; consider adding audit logging for production use
161+
4. **Error Handling**: Proper error handling prevents crashes and provides useful feedback
162+
163+
## Performance Notes
164+
165+
- Native scanning is fastest for small port ranges (< 100 ports)
166+
- Nmap is recommended for large port ranges (> 1000 ports)
167+
- Timeout affects scan duration: lower timeout = faster scans but more false negatives
168+
- Parallel scanning is not implemented to avoid overwhelming the target system
169+
170+
## Future Enhancements
171+
172+
Potential improvements for future versions:
173+
- UDP port scanning support
174+
- Parallel/concurrent scanning with configurable thread pool
175+
- Export results to CSV/JSON
176+
- Scan history and saved configurations
177+
- Port range presets (common ports, all ports, etc.)
178+
- Integration with vulnerability databases
179+
- Network range scanning (CIDR notation)
180+
- Custom service detection rules
181+
182+
## Testing
183+
184+
The module has been verified to:
185+
- ✅ Compile successfully (both Rust and TypeScript)
186+
- ✅ Pass type checking
187+
- ✅ Integrate properly with existing Tauri commands
188+
- ✅ Follow existing code patterns and structure
189+
190+
Manual testing recommended:
191+
- Test scanning localhost (127.0.0.1)
192+
- Test scanning with various port ranges
193+
- Test with and without nmap installed
194+
- Test timeout adjustments
195+
- Verify service detection accuracy
196+
197+
## Dependencies
198+
199+
### Rust:
200+
- `serde` - Serialization/deserialization
201+
- `std::net::TcpStream` - TCP connections
202+
- `std::process::Command` - Execute nmap
203+
- `std::time::Duration` - Timeout handling
204+
205+
### TypeScript/React:
206+
- `@tauri-apps/api` - Tauri API bindings
207+
- `antd` - UI components
208+
- `react` - UI framework
209+
210+
No additional dependencies were added to the project.

0 commit comments

Comments
 (0)