Programmazione agentica con IA: creare un piccolo port scanner Python su Windows

Introduzione

Forse oggi una guida di questo tipo potrebbe sembrare quasi inutile: basta chiedere a un’intelligenza artificiale “come faccio a creare un programma?” o addirittura “realizza un programma che …” e molto probabilmente riceveremo una risposta lunga, dettagliata e magari anche più precisa di quella che potrei scrivere io in un articolo.

Ma il punto non è sostituire ChatGPT, Codex CLI o qualsiasi altro strumento IA. Il punto è organizzare le idee.

Questa guida vuole essere un piccolo punto di partenza: un modo semplice per capire come impostare un progetto, come preparare i file, come scrivere i prompt, come usare Git per non perdere il controllo e come far lavorare un agente IA in modo ordinato.

Tutto molto semplificato!

In questa guida useremo Python perché oggi è probabilmente uno dei modi più semplici per avvicinarsi alla programmazione.

Python ha una sintassi molto leggibile. Le istruzioni sembrano quasi frasi scritte in inglese. Questo lo rende adatto a chi sta iniziando, perché permette di concentrarsi sul ragionamento, sul problema da risolvere e sul funzionamento del programma, senza perdersi subito in troppi dettagli tecnici.

Python viene utilizzato in molte classi terze degli istituti tecnici italiani per introdurre la programmazione imperativa di base: variabili, input, output, condizioni, cicli, funzioni e primi algoritmi. È anche il linguaggio che uso nella mia scuola per introdurre gli studenti nei primi passi del pensiero computazionale e della programmazione.

L’idea è questa: anche uno studente o un appassionato che non ha mai programmato dovrebbe riuscire ad aprire il file generato con l’aiuto dell’agente IA, leggere il codice e capire almeno a grandi linee cosa sta succedendo, anche perché la descrizione del progetto, delle regole e del comportamento atteso del programma è già spiegata nei vari file Markdown (.md) che prepariamo prima dello sviluppo.

In questo articolo vedremo un piccolo esempio pratico di programmazione agentica con IA: useremo ChatGPT per ragionare sul progetto e preparare i prompt, e Codex CLI per far lavorare l’agente direttamente sui file.

Il progetto sarà volutamente semplice: un piccolo port scanner TCP in Python.

Non spiegherò come installare Python, Git, Visual Studio Code o Codex CLI. La guida diventerebbe troppo lunga e andrebbe fuori tema. Se non avete ancora questi strumenti installati, potete cercare le guide ufficiali sui rispettivi siti oppure chiedere al vostro assistente di intelligenza artificiale di aiutarvi passo passo. Anche questo fa parte del percorso: imparare a cercare, fare domande precise, provare, sbagliare, correggere e riprovare.

Software utilizzati

Per questo esempio immaginiamo un normale PC Windows con:

Perché partire da Windows

Questo articolo è scritto pensando a utenti Windows per un motivo molto semplice: nella mia esperienza, la maggior parte degli studenti e degli appassionati che vogliono avvicinarsi alla programmazione parte quasi sempre da un computer Windows.

Chi non ha ancora esperienza nello sviluppo software difficilmente usa già un sistema Unix-like come GNU/Linux. Per questo l’idea è rendere il primo approccio più accessibile possibile: accendere il PC, aprire PowerShell, usare Python, Git, ChatGPT e Codex CLI, e iniziare subito a provare.

Poi, naturalmente, un ottimo passaggio successivo è installare Linux, anche solo dentro una macchina virtuale, e iniziare a familiarizzare con terminale, filesystem, permessi, pacchetti e strumenti da riga di comando.

Per chi vuole fare questo passaggio, sul mio canale YouTube trovate una vecchia video guida in cui spiego come installare Debian GNU/Linux su VirtualBox, più altri video dedicati ai comandi di base.

Per chi vuole “passare al lato oscuro della forza”, può partire da qui:
Installare Debian GNU/Linux su VirtualBox: https://youtu.be/YuQfJOKZ36E?si=seahU_agvMy5CjwK

Obiettivo del progetto

Vogliamo creare un piccolo programma Python che controlla alcune porte TCP di un host autorizzato.

Esempio:

python .\src\portscanner.py --host 127.0.0.1 --ports 22,80,443 --timeout 0.5

Output atteso:

Target: 127.0.0.1
Porta 22    chiusa
Porta 80    aperta
Porta 443   chiusa

Struttura del progetto

python-port-scanner/
├── AGENTS.md
├── LEGGIMI.md
├── doc/
│   ├── DESCRIZIONE_PROGETTO.md
│   ├── SPECIFICHE.md
│   ├── REGOLE_SICUREZZA.md
│   └── PROMPT.md
└── src/
    └── portscanner.py

Creazione progetto da PowerShell

Se non ti sono chiari alcuni comandi chiedi a ChatGPT ;-)

mkdir python-port-scanner
cd python-port-scanner

git init

mkdir src
mkdir doc

Ambiente Python:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

python -m pip install --upgrade pip

Primo salvataggio Git:

git add .
git commit -m "Creazione struttura iniziale progetto"

Che cos’è AGENTS.md

AGENTS.md è il file di istruzioni che Codex CLI legge prima di lavorare sul progetto.

Serve a spiegare all’agente:

  • che tipo di software stiamo sviluppando;
  • quali file deve modificare;
  • quali comandi usare;
  • quali regole tecniche e di sicurezza rispettare.

In pratica è una piccola “guida interna” del progetto: aiuta Codex a non improvvisare e a seguire il nostro metodo di lavoro.

File AGENTS.md

Copiare nel file AGENTS.md:

# AGENTS.md

## Contesto

Questo progetto è un piccolo port scanner TCP scritto in Python.

Il progetto è didattico e serve per imparare:

- programmazione Python da terminale;
- uso del modulo socket;
- argomenti da riga di comando;
- validazione input;
- uso di Git e GitHub;
- sviluppo agentico con ChatGPT e Codex CLI.

Sistema operativo di riferimento: Windows 10/11.

## Obiettivo

Creare un programma eseguibile da PowerShell:

python .\src\portscanner.py --host 127.0.0.1 --ports 22,80,443 --timeout 0.5

Il programma deve indicare se le porte TCP richieste sono aperte o chiuse.

## Limiti di sicurezza

Il software può essere usato solo su:

- localhost;
- computer propri;
- macchine virtuali di laboratorio;
- reti private autorizzate;
- sistemi con autorizzazione esplicita.

Non implementare:

- scansioni massive;
- scansioni di subnet;
- tecniche stealth;
- exploit;
- brute force;
- fingerprinting avanzato;
- evasione firewall/IDS;
- moduli offensivi.

## Requisiti tecnici

Usare Python standard library.

Moduli consigliati:

- argparse;
- socket;
- logging;
- sys;
- typing.

## Struttura

Codice principale:

src/portscanner.py

Documentazione:

doc/

## Comandi

Eseguire programma:

python .\src\portscanner.py --host 127.0.0.1 --ports 22,80,443 --timeout 0.5

Controllare modifiche Git:

git status
git diff

## Regole operative

- Non eseguire commit Git automaticamente.
- Prima di modificare, spiega brevemente cosa farai.
- Dopo la modifica, riepiloga i file cambiati.
- Mantieni il codice semplice.
- Valida sempre gli input.
- Gestisci errori e timeout.
- Non cambiare lo scopo del progetto.

File DESCRIZIONE_PROGETTO.md

Copiare in doc/DESCRIZIONE_PROGETTO.md:

# Descrizione progetto

Il progetto consiste nella creazione di un piccolo port scanner TCP in Python.

Il software deve funzionare su Windows tramite PowerShell.

Obiettivi didattici:

- usare Python per attività di rete;
- capire host, porta TCP e timeout;
- usare il modulo socket;
- validare input da terminale;
- gestire errori;
- usare Git e GitHub;
- lavorare con ChatGPT e Codex CLI.

Il programma è solo per uso didattico e autorizzato.

File SPECIFICHE.md

Copiare in doc/SPECIFICHE.md:

# Specifiche tecniche

## Programma

src/portscanner.py

## Argomenti

--host

Host o indirizzo IP da controllare.

Esempi:

127.0.0.1
localhost
192.168.1.10

--ports

Lista di porte TCP separate da virgola.

Esempio:

22,80,443,3306

--timeout

Timeout in secondi.

Valore predefinito:

1.0

## Validazione

Il programma deve verificare che:

- host non sia vuoto;
- le porte siano numeri interi;
- le porte siano tra 1 e 65535;
- i duplicati vengano rimossi;
- timeout sia maggiore di zero.

## Output

Esempio:

Target: 127.0.0.1
Porta 22 chiusa
Porta 80 aperta
Porta 443 chiusa

## Errori

In caso di input errato, mostrare un messaggio chiaro e terminare con codice diverso da zero.

File REGOLE_SICUREZZA.md

Copiare in doc/REGOLE_SICUREZZA.md:

# Regole di sicurezza

Questo software è solo didattico.

## Consentito

Usare il programma su:

- localhost;
- PC propri;
- macchine virtuali;
- reti private autorizzate;
- sistemi con permesso esplicito.

## Non consentito

Non usare il programma per:

- scansionare IP pubblici di terzi;
- eseguire scansioni massive;
- cercare vulnerabilità senza permesso;
- aggirare protezioni;
- raccogliere informazioni su sistemi non propri.

## Limiti

Il progetto non deve includere:

- scansione subnet;
- scansione multi-thread aggressiva;
- stealth scan;
- exploit;
- brute force;
- moduli offensivi.

File PROMPT.md

Copiare in doc/PROMPT.md:

# Prompt sviluppo agentico

In questo file salviamo i prompt usati con ChatGPT e Codex CLI.

Serve per:

- ricordare come è stato sviluppato il progetto;
- ripetere il flusso di lavoro;
- migliorare i prompt successivi;
- documentare le decisioni.

Primo ciclo: realizzazione della versione base

Aprire Codex CLI nella cartella del progetto:

codex

Prompt da incollare:

Leggi AGENTS.md e tutti i file nella directory doc/ prima di modificare il progetto.

Implementa la prima versione funzionante del port scanner TCP didattico.

Requisiti:

- implementa src/portscanner.py;
- usa argparse;
- accetta --host, --ports e --timeout;
- interpreta --ports come lista di porte TCP separate da virgola;
- valida porte intere tra 1 e 65535;
- rimuovi porte duplicate;
- usa socket.create_connection con timeout;
- mostra per ogni porta se è aperta o chiusa;
- gestisci errori in modo chiaro;
- evita traceback non controllati;
- non aggiungere funzioni offensive;
- non aggiungere scansioni massive;
- non aggiungere scansioni di subnet;
- non aggiungere tecniche stealth.

Non eseguire commit Git.

Alla fine riepiloga file modificati e comandi per provare il programma.

Verifica dell’output di Codex CLI con ChatGPT

Dopo l’esecuzione di Codex CLI, conviene fare una verifica veloce usando la chat di progettazione in ChatGPT.

Il flusso è semplice:

  1. in Codex CLI copiamo l’output usando il comando /copy;
  2. incolliamo il log nella chat di ChatGPT;
  3. chiediamo di analizzare cosa è stato modificato;
  4. verifichiamo se ci sono errori, file cambiati in modo non previsto o suggerimenti utili;
  5. se l’analisi è positiva e il progetto funziona, possiamo procedere con il salvataggio tramite Git.

In questo modo ChatGPT viene usato come secondo livello di controllo: Codex CLI modifica i file, mentre ChatGPT ci aiuta a leggere e valutare il risultato prima di confermare le modifiche.

IMPORTANTE: prima di eseguire il programma, apriamo il file .py generato, leggiamo il codice e proviamo a capire a grandi linee come funziona. Solo dopo questa verifica eseguiamo il file Python per provarlo.

python .\src\portscanner.py --host 127.0.0.1 --ports 22,80,443 --timeout 0.5

Controlliamo cosa ha modificato l’agente:

git status
git diff

Se tutto funziona:

git add .
git commit -m "Implementazione versione base port scanner TCP"
git tag v0.1.0

Pubblicazione su GitHub con GitHub CLI:

gh repo create python-port-scanner --private --source=. --remote=origin --push
git push origin v0.1.0

Oppure, se il repository esiste già:

git remote add origin https://github.com/NOMEUTENTE/python-port-scanner.git
git branch -M main
git push -u origin main
git push origin v0.1.0

Secondo ciclo: piccolo miglioramento

Creiamo un branch separato:

git switch -c miglioramento-cli

Prompt da incollare in Codex CLI:

Leggi AGENTS.md e la directory doc/ prima di modificare il progetto.

Migliora il port scanner senza cambiare lo scopo.

Puoi modificare solo:

- src/portscanner.py
- LEGGIMI.md
- doc/PROMPT.md, solo se necessario

Modifiche richieste:

- ordina le porte prima della scansione;
- rimuovi duplicati;
- migliora i messaggi di errore;
- restituisci exit code 0 se l'esecuzione è valida;
- restituisci exit code diverso da zero per input non valido;
- aggiorna LEGGIMI.md con esempi PowerShell.

Non aggiungere:

- multi-thread;
- scansione subnet;
- stealth;
- fingerprinting;
- rilevamento vulnerabilità;
- funzioni offensive.

Non eseguire commit Git.

Alla fine riepiloga file modificati e comandi per provare il programma.

Come prima verifica dell’output di Codex CLI con ChatGPT, leggiamo il codice e proviamo:

python .\src\portscanner.py --host 127.0.0.1 --ports 443,80,80,22 --timeout 0.5

Controlliamo le modifiche:

git status
git diff

Se tutto è corretto:

git add .
git commit -m "Miglioramento CLI e validazione input"
git tag v0.2.0

git push -u origin miglioramento-cli
git push origin v0.2.0

Merge su main:

git switch main
git merge miglioramento-cli
git push origin main

Se Codex rompe il progetto

Se le modifiche non sono ancora state salvate:

git restore .

Se vogliamo eliminare il branch di lavoro:

git switch main
git branch -D miglioramento-cli

Se abbiamo già fatto merge e vogliamo annullare l’ultimo commit:

git revert HEAD
git push origin main

Se il progetto è personale e vogliamo tornare alla versione v0.1.0:

git reset --hard v0.1.0
git push --force-with-lease origin main

Quest’ultimo comando va usato con attenzione perché riscrive lo stato remoto.

Nota sui test

In questa guida abbiamo volutamente lasciato fuori la parte dei test automatici per non complicare troppo il primo approccio.

In un progetto reale, però, i test sono fondamentali: servono a verificare che il programma continui a funzionare anche dopo modifiche, miglioramenti o interventi dell’agente IA.

Per ora ci limitiamo a provare manualmente il programma da PowerShell.

Il flusso completo

Il metodo è questo:

idea
→ file di progetto
→ AGENTS.md
→ prompt
→ Codex CLI
→ verifica output Codex CLI con /copy su ChatGPT
→ lettura/studio del codice generato
→ prova manuale
→ git diff
→ commit
→ tag
→ GitHub
→ nuovo ciclo

È un progetto piccolissimo, ma il flusso è reale.

La cosa importante non è il port scanner. La cosa importante è capire come lavorare con gli agenti IA senza perdere controllo del progetto.

ChatGPT aiuta a ragionare e preparare prompt.
Codex CLI lavora sui file.
Git permette di tornare indietro.
GitHub conserva le versioni.

Questo è il punto di partenza per programmare con l’IA in modo serio, anche da Windows, anche partendo da un progetto molto semplice.

Conclusione

La programmazione agentica non sostituisce il programmatore ma lo potenzia.

È un acceleratore, un aiuto concreto, un modo per diventare più produttivi e trasformare più velocemente un’idea in un progetto funzionante. Può permettere anche a un singolo sviluppatore di riprendere quel progetto rimasto nel cassetto per mancanza di tempo, risorse o supporto tecnico.

Ma l’agente IA non lavora bene da solo. Serve qualcuno che sappia guidarlo, correggerlo, limitarlo e verificare quello che produce. Lo sviluppo agentico richiede progettazione, metodo e capacità di orchestrazione. Bisogna sapere cosa chiedere, come chiederlo, come controllare il risultato e quando fermare l’agente prima che complichi inutilmente il progetto.

Per questo restano fondamentali le basi vere dell’informatica:

  • Capacità di analisi del problema (Pensiero computazionale)
  • Algoritmi
  • Strutture dati
  • Programmazione
  • Progettazione software
  • Sicurezza informatica
  • Testing
  • Debugging
  • Gestione delle versioni
  • Documentazione

La programmazione agentica, o “programmazione automatica” come viene chiamata da Salvatore Sanfilippo, non è una scorciatoia per evitare di studiare. È uno strumento per studiare meglio, sperimentare di più e applicare subito quello che si impara.

Il mio consiglio, per chi vuole andare oltre la superficie, è partire dalle basi solide:

  1. Seguire il corso C di Salvatore Sanfilippo: https://youtube.com/playlist?list=PLrEMgOSrS_3cFJpM2gdw8EGFyRBZOyAKY&si=OGz5upbMKIGCeRwn
  2. Leggere il libro K&R — Il linguaggio C, una vera pietra miliare dello sviluppo software: https://it.wikipedia.org/wiki/Il_linguaggio_C
  3. Usare l’intelligenza artificiale che si preferisce come mentor, tutor e guida allo studio.
  4. Studiare, provare, scrivere codice, studiare, …

Prima chi voleva imparare qualcosa aveva soprattutto Internet, forum, blog, manuali e tanta pazienza. Oggi può anche chiedere a una rete neurale di spiegare un argomento in modo più semplice, fare esempi, proporre esercizi, correggere un errore, confrontare soluzioni e accompagnarlo nello studio.

Questo è un enorme vantaggio, ma va usato nel modo giusto. L’IA può scrivere codice, proporre soluzioni e velocizzare il lavoro. Ma la qualità del software dipende ancora dalla qualità delle idee, delle competenze e delle decisioni di chi lo progetta.

Il vero valore della programmazione agentica è questo: ti aiuta a concentrarti sul progetto, sull’architettura, sulle scelte tecniche e sulla realizzazione delle tue idee. Ti permette di studiare, approfondire e applicare subito.

Non basta restare in superficie. Bisogna scendere nel dettaglio, capire come funzionano le cose e continuare a studiare.

Solo così la programmazione agentica diventa davvero utile: non un modo per programmare senza sapere, ma un modo per costruire meglio, imparare più velocemente e portare finalmente a termine le proprie idee.

Percorsi collegati