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

# 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

# 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 :

allowed_read_paths:
  - /var/www/mathematiques
  - /var/www/html
  # Ajouter d'autres chemins si nécessaire

🏃 Lancement

Mode développement

# 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

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

GET /api/files/read?path=/var/www/mathematiques/index.php

3. Arborescence (tree)

GET /api/files/tree?path=/var/www/mathematiques&max_depth=5

4. Rechercher dans les fichiers (grep)

GET /api/files/grep?path=/var/www/mathematiques&pattern=function&file_pattern=*.php

Exemples avec curl

# 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

# 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