Skip to content

Commit 9cc6a52

Browse files
npv2k1npv2k1
authored
Merge pull request #12 from pnstack/copilot/fix-805acf60-4017-47c3-ae72-3a0b00bb0303
Add Port Explorer module with native and nmap scanning support
2 parents 06956de + 898dde6 commit 9cc6a52

10 files changed

Lines changed: 687 additions & 6 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.

‎README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,20 @@
44

55
This template should help get you started developing with Tauri, React and Typescript in Vite.
66

7+
## Features
8+
9+
### Port Explorer
10+
A powerful port scanning module that allows you to scan ports on your local machine or remote IP addresses. Features include:
11+
- **Native TCP scanning** built with Rust
12+
- **Nmap integration** for advanced scanning (optional)
13+
- Configurable port ranges and timeout settings
14+
- Service detection for common ports
15+
- Interactive results table with filtering and sorting
16+
17+
To access: Navigate to **Tauri > PortExplorer** in the application.
18+
19+
See [Port Explorer Documentation](src/modules/tauri/components/port-explorer/README.md) for more details.
20+
721
## Recommended IDE Setup
822

923
- [VS Code](https://code.visualstudio.com/) + [Tauri](https://marketplace.visualstudio.com/items?itemName=tauri-apps.tauri-vscode) + [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer)

‎src-tauri/src/commands/mod.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
use crate::db;
22
pub mod blockchain;
3+
pub mod port_scanner;
34
#[tauri::command]
45
pub fn greet(name: &str) -> String {
56
println!("Hello, {}!", name);

‎src-tauri/src/commands/port_scanner.rs‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
use crate::modules::port_scanner::{scan_ports, PortScanResult, ScanOptions};
2+
3+
#[tauri::command]
4+
pub fn scan_ports_command(
5+
host: String,
6+
start_port: u16,
7+
end_port: u16,
8+
use_nmap: bool,
9+
timeout_ms: u64,
10+
) -> Result<Vec<PortScanResult>, String> {
11+
let options = ScanOptions {
12+
host,
13+
start_port,
14+
end_port,
15+
use_nmap,
16+
timeout_ms,
17+
};
18+
19+
scan_ports(options)
20+
}
21+
22+
#[tauri::command]
23+
pub fn check_nmap_available() -> bool {
24+
std::process::Command::new("nmap")
25+
.arg("--version")
26+
.output()
27+
.is_ok()
28+
}

‎src-tauri/src/main.rs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,8 @@ fn main() {
3838
commands::blockchain::init_blockchain_command,
3939
commands::blockchain::add_block_command,
4040
commands::blockchain::get_blocks_command,
41+
commands::port_scanner::scan_ports_command,
42+
commands::port_scanner::check_nmap_available,
4143
])
4244
.setup({
4345
let python_server = Arc::clone(&python_server);

‎src-tauri/src/modules/mod.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
11
pub mod blockchain;
2+
pub mod port_scanner;
23
pub mod python;

0 commit comments

Comments
 (0)