Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 53 additions & 0 deletions .github/workflows/deploy.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
name: Deploy to GitHub Pages

on:
push:
branches: [ feature/ui-mock-prototype ]
workflow_dispatch: # Allow manual trigger

permissions:
contents: write
pages: write
id-token: write

jobs:
build-and-deploy:
runs-on: ubuntu-latest

steps:
- name: Checkout 🛎️
uses: actions/checkout@v4

- name: Setup Node.js 📦
uses: actions/setup-node@v4
with:
node-version: '18'
cache: 'npm'
cache-dependency-path: frontend/package-lock.json

- name: Install Dependencies 📚
working-directory: ./frontend
run: npm ci

- name: Build Project 🔧
working-directory: ./frontend
run: npm run build
env:
GENERATE_SOURCEMAP: false
ESLINT_NO_DEV_ERRORS: true
CI: false

- name: Add .nojekyll file
run: touch ./frontend/build/.nojekyll

- name: Deploy to GitHub Pages 🚀
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./frontend/build
publish_branch: gh-pages
force_orphan: true
user_name: 'github-actions[bot]'
user_email: 'github-actions[bot]@users.noreply.github.com'
enable_jekyll: false
cname: false
5 changes: 1 addition & 4 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,4 @@ coverage.xml
/data/
captures/
# Allow frontend mock data
!frontend/src/data/

#ignore additional file
.setup_complete
!frontend/src/data/
Empty file added .setup_complete
Empty file.
Empty file added DEPLOYMENT.md
Empty file.
Empty file added GITHUB_PAGES.md
Empty file.
302 changes: 302 additions & 0 deletions QUICK_REFERENCE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,302 @@
# Exfil-Sentry Quick Reference 🚀

## Container Overview

| # | Container | Port | Purpose | Location |
|---|-----------|------|---------|----------|
| 1 | frontend | 3000 | Web Dashboard | `containers/frontend/` |
| 2 | backend | 8000 | API Server | `containers/backend/` |
| 3 | database | 5432 | PostgreSQL | (Official Image) |
| 4 | detector | - | Traffic Analysis | `containers/detector/` |
| 5 | attacker | 5000 | Attack Simulator | `containers/attacker/` |
| 6 | victim-tigervnc | 5900 | Test VNC Server | `containers/victim-tigervnc/` |
| 7 | victim-realvnc | 5901 | Test VNC Server | `containers/victim-realvnc/` |

---

## Essential Commands

```bash
# Setup (first time only)
./scripts/setup.sh

# Start system
./scripts/run.sh

# Stop system
./scripts/stop.sh

# Stop and delete all data
./scripts/stop.sh --clean

# View logs
docker compose logs -f [container-name]

# Restart single container
docker compose restart [container-name]

# Check container status
docker compose ps
```

---

## Access Points

| Service | URL | Credentials |
|---------|-----|-------------|
| Dashboard | http://localhost:3000 | admin/admin123 |
| API Docs | http://localhost:8000/docs | (Same as above) |
| Attacker API | http://localhost:5000 | (No auth) |
| TigerVNC | localhost:5900 | vncpass |
| RealVNC | localhost:5901 | vncpass |

---

## API Endpoints Quick Reference

### Attack Simulation
```bash
# Launch attack
POST /api/v1/attack/start
Body: {"attack_type": "clipboard_exfil", "target": "tigervnc"}

# List attack types
GET /api/v1/attack/types

# View attack history
GET /api/v1/attack/history
```

### Security Alerts
```bash
# List all alerts
GET /api/v1/alerts

# Get specific alert
GET /api/v1/alerts/{id}

# Alert statistics
GET /api/v1/alerts/stats/summary
```

### Firewall
```bash
# Block IP
POST /api/v1/firewall/block?ip_address=192.168.1.100

# Unblock IP
POST /api/v1/firewall/unblock?ip_address=192.168.1.100

# List blocked IPs
GET /api/v1/firewall/blocked-ips
```

---

## File Structure

```
containers/
├── backend/ # Your FastAPI work goes here
├── frontend/ # Your React work goes here
├── detector/ # Modify detection rules here
├── attacker/ # Add attack types here
├── victim-tigervnc/
└── victim-realvnc/

scripts/
├── setup.sh # First-time setup
├── run.sh # Daily start
└── stop.sh # Daily stop

docs/
├── DEPLOYMENT.md # How to deploy
├── PROBLEM_STATEMENT.md
└── ROADMAP.md
```

---

## Common Tasks

### Add New Detection Rule
1. Edit `containers/detector/detector.py`
2. Add pattern to `SUSPICIOUS_PATTERNS` dict
3. Restart: `docker compose restart detector`

### Add New Attack Type
1. Edit `containers/attacker/attacker.py`
2. Add method to `VNCAttacker` class
3. Update route in Flask app
4. Restart: `docker compose restart attacker`

### Modify Backend Endpoint
1. Edit file in `containers/backend/api/v1/endpoints/`
2. Restart: `docker compose restart backend`

### Update Frontend
1. Edit files in `containers/frontend/src/`
2. Changes auto-reload (hot reload enabled)

---

## Troubleshooting

### Container won't start
```bash
docker compose logs [container-name]
docker compose restart [container-name]
```

### Database connection error
```bash
docker compose restart database
docker compose restart backend
```

### Port already in use
```bash
# Find what's using port 3000
netstat -tuln | grep :3000
# Kill process or change port in docker-compose.yml
```

### Reset everything
```bash
./scripts/stop.sh --clean
./scripts/setup.sh
```

---

## Development Workflow

1. **Make changes** in `containers/[service]/`
2. **Test locally**:
```bash
docker compose restart [service]
docker compose logs -f [service]
```
3. **Verify** at http://localhost:3000
4. **Commit**:
```bash
git add .
git commit -m "Description"
git push
```

---

## Attack-Detection-Prevention Loop

```
1. Launch Attack (Dashboard or API)
2. Attacker hits Victim (VNC)
3. Detector captures traffic (Scapy)
4. Alert created in Database
5. Alert displayed in Dashboard
6. User blocks IP (iptables)
```

---

## Environment Variables

### Backend
```env
DATABASE_URL=postgresql://exfilsentry:password@database:5432/exfilsentry
ATTACKER_URL=http://attacker:5000
DEBUG=true
```

### Detector
```env
DATABASE_URL=postgresql://exfilsentry:password@database:5432/exfilsentry
NETWORK_INTERFACE=eth0
```

---

## Health Checks

```bash
# All services
docker compose ps

# Specific health endpoints
curl http://localhost:8000/health
curl http://localhost:5000/health

# Database
docker compose exec database pg_isready -U exfilsentry
```

---

## Backup & Restore

```bash
# Backup database
docker compose exec database pg_dump -U exfilsentry exfilsentry > backup.sql

# Restore database
docker compose exec -T database psql -U exfilsentry exfilsentry < backup.sql
```

---

## Performance Tips

- **Detector**: Adjust `SUSPICIOUS_PATTERNS` threshold
- **Backend**: Add database indexes
- **Frontend**: Use React.memo for heavy components
- **Database**: Regular VACUUM and ANALYZE

---

## Security Checklist

- [ ] Change default passwords (admin/admin123)
- [ ] Use HTTPS in production
- [ ] Restrict database port (5432)
- [ ] Enable firewall rules
- [ ] Regular security updates
- [ ] Monitor logs for anomalies

---

## Support

- **Documentation**: `/docs` folder
- **Logs**: `docker compose logs [service]`
- **Issues**: GitHub Issues
- **Team Chat**: [Your communication channel]

---

## Key Files

| File | Purpose |
|------|---------|
| `docker-compose.yml` | Service definitions |
| `README.md` | Project overview |
| `REFACTORING_SUMMARY.md` | What we changed |
| `docs/DEPLOYMENT.md` | Deployment guide |
| `docs/PROBLEM_STATEMENT.md` | Hackathon problem |

---

**Remember**:
- Setup once: `./scripts/setup.sh`
- Daily: `./scripts/run.sh` and `./scripts/stop.sh`
- Each container = separate folder in `containers/`

---

*Last Updated: November 2025*
Loading
Loading