213 lines
4.6 KiB
Markdown
213 lines
4.6 KiB
Markdown
# Jetson Agent API
|
|
|
|
API middleware sécurisée pour accès lecture aux fichiers du Jetson Nano.
|
|
|
|
## 📋 Description
|
|
|
|
Cette API permet un accès sécurisé et contrôlé aux fichiers du Jetson Nano, principalement pour permettre à des LLMs (Claude, Gemini, etc.) de lire et analyser les fichiers de l'application web mathématiques.
|
|
|
|
## ✨ Fonctionnalités
|
|
|
|
- ✅ **Lecture de fichiers** sécurisée avec validation de chemins
|
|
- ✅ **Listing de répertoires** avec support récursif
|
|
- ✅ **Arborescence** (tree) de dossiers
|
|
- ✅ **Recherche** (grep) dans les fichiers
|
|
- ✅ **Validation** d'extensions et tailles de fichiers
|
|
- ✅ **API REST** avec documentation Swagger intégrée
|
|
|
|
## 🚀 Installation
|
|
|
|
### Prérequis
|
|
|
|
- Python 3.11+
|
|
- pip
|
|
- Git
|
|
|
|
### Installation rapide
|
|
|
|
```bash
|
|
# Se positionner dans le projet
|
|
cd ~/projects/jetson-agent
|
|
|
|
# Créer environnement virtuel
|
|
python3 -m venv .venv
|
|
|
|
# Activer l'environnement
|
|
source .venv/bin/activate
|
|
|
|
# Installer les dépendances
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
## ⚙️ Configuration
|
|
|
|
### 1. Créer le fichier .env
|
|
|
|
```bash
|
|
# Copier l'exemple
|
|
cp config/example.env .env
|
|
|
|
# Générer une clé secrète JWT
|
|
openssl rand -hex 32
|
|
|
|
# Éditer .env et remplacer JWT_SECRET_KEY par la clé générée
|
|
nano .env
|
|
```
|
|
|
|
### 2. Adapter les chemins autorisés
|
|
|
|
Éditer `config/allowed_paths.yaml` pour ajouter/retirer des chemins :
|
|
|
|
```yaml
|
|
allowed_read_paths:
|
|
- /var/www/mathematiques
|
|
- /var/www/html
|
|
# Ajouter d'autres chemins si nécessaire
|
|
```
|
|
|
|
## 🏃 Lancement
|
|
|
|
### Mode développement
|
|
|
|
```bash
|
|
# Activer l'environnement
|
|
source .venv/bin/activate
|
|
|
|
# Lancer l'API
|
|
cd src
|
|
uvicorn jetson_agent.main:app --reload --host 0.0.0.0 --port 8000
|
|
```
|
|
|
|
L'API est accessible sur : `http://localhost:8000`
|
|
|
|
Documentation Swagger : `http://localhost:8000/docs`
|
|
|
|
### Mode production (avec systemd)
|
|
|
|
Créer un service systemd (à venir).
|
|
|
|
## 📚 Utilisation de l'API
|
|
|
|
### Endpoints disponibles
|
|
|
|
#### 1. Lister les fichiers d'un dossier
|
|
|
|
```bash
|
|
GET /api/files/list?path=/var/www/mathematiques
|
|
|
|
# Avec récursion
|
|
GET /api/files/list?path=/var/www/mathematiques&recursive=true&max_depth=3
|
|
```
|
|
|
|
#### 2. Lire un fichier
|
|
|
|
```bash
|
|
GET /api/files/read?path=/var/www/mathematiques/index.php
|
|
```
|
|
|
|
#### 3. Arborescence (tree)
|
|
|
|
```bash
|
|
GET /api/files/tree?path=/var/www/mathematiques&max_depth=5
|
|
```
|
|
|
|
#### 4. Rechercher dans les fichiers (grep)
|
|
|
|
```bash
|
|
GET /api/files/grep?path=/var/www/mathematiques&pattern=function&file_pattern=*.php
|
|
```
|
|
|
|
### Exemples avec curl
|
|
|
|
```bash
|
|
# Health check
|
|
curl http://localhost:8000/api/health
|
|
|
|
# Lister fichiers
|
|
curl "http://localhost:8000/api/files/list?path=/var/www/mathematiques"
|
|
|
|
# Lire un fichier
|
|
curl "http://localhost:8000/api/files/read?path=/var/www/mathematiques/index.php"
|
|
|
|
# Arborescence
|
|
curl "http://localhost:8000/api/files/tree?path=/var/www/mathematiques&max_depth=3"
|
|
|
|
# Recherche
|
|
curl "http://localhost:8000/api/files/grep?path=/var/www/mathematiques&pattern=mysql&file_pattern=*.php"
|
|
```
|
|
|
|
## 🔐 Sécurité
|
|
|
|
### Chemins autorisés
|
|
|
|
L'API n'autorise l'accès qu'aux chemins définis dans `config/allowed_paths.yaml`.
|
|
|
|
### Validation
|
|
|
|
- ✅ Pas de traversal de chemin (`..`)
|
|
- ✅ Blocklist de chemins sensibles (`/etc`, `/root`, etc.)
|
|
- ✅ Validation d'extensions de fichiers
|
|
- ✅ Limite de taille de fichiers (10 MB par défaut)
|
|
- ✅ Limite du nombre de résultats
|
|
|
|
### Recommandations
|
|
|
|
- [ ] Utiliser HTTPS en production (via nginx reverse proxy)
|
|
- [ ] Configurer un pare-feu (UFW)
|
|
- [ ] Limiter l'accès IP si possible
|
|
- [ ] Activer l'authentification JWT (à venir)
|
|
|
|
## 📁 Structure du projet
|
|
|
|
```
|
|
jetson-agent/
|
|
├── src/
|
|
│ └── jetson_agent/
|
|
│ ├── __init__.py
|
|
│ ├── main.py # Point d'entrée FastAPI
|
|
│ ├── config.py # Configuration
|
|
│ ├── path_validator.py # Validation de chemins
|
|
│ └── api/
|
|
│ ├── __init__.py
|
|
│ └── filesystem.py # Endpoints fichiers
|
|
├── config/
|
|
│ ├── example.env
|
|
│ └── allowed_paths.yaml
|
|
├── tests/ # Tests (à venir)
|
|
├── requirements.txt
|
|
└── README.md
|
|
```
|
|
|
|
## 🧪 Tests
|
|
|
|
```bash
|
|
# Installer les dépendances de dev
|
|
pip install pytest pytest-asyncio httpx
|
|
|
|
# Lancer les tests (à venir)
|
|
pytest
|
|
```
|
|
|
|
## 📝 TODO / Roadmap
|
|
|
|
- [ ] Authentification JWT
|
|
- [ ] Endpoints base de données (lecture MariaDB)
|
|
- [ ] Rate limiting
|
|
- [ ] Logs structurés
|
|
- [ ] Tests unitaires
|
|
- [ ] Déploiement systemd
|
|
- [ ] Documentation API complète
|
|
- [ ] Support GPIO (lecture/écriture pins)
|
|
|
|
## 🤝 Contribution
|
|
|
|
Projet personnel pour contrôle du Jetson Nano via LLM.
|
|
|
|
## 📄 Licence
|
|
|
|
Privé - Usage personnel
|
|
|
|
## 👤 Auteur
|
|
|
|
Nicolas - 2025
|