jetson-agent/README.md

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

# 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