Implement Device Identification (2.2.4)

Aperta
  • Qualcosa non va?
#63 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
35/100
Tipo di issue
Funzionalità
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
python
Ambito
backend, backend-api-design

Direzione di ricerca

Start by reading the scan code under backend/services/scan/, especially match_oui.py, then inspect the referenced specifications and the completed dependencies (#36, #48, and #39). Implement the six ordered subtasks, beginning with the shared evidence record and weights; use hand-made evidence and reference rules for unit tests. Done means saved devices have evidence-backed scores, types, levels, and flags, rescans do not change scores, retired signatures do not match, and the unit tests pass.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

backend High Priority Parent task

What to do

Build the Identification Manager (2.2.4) and its four leaves, which turn a device's evidence into an identification: 2.2.4.1 Match Evidence to Reference Data, 2.2.4.2 Resolve Conflicting Evidence, 2.2.4.3 Calculate Confidence Score and 2.2.4.4 Assign Identification Level. Then plug it into the scan in place of M2's provisional "OUI match = partial" rule, so every saved device gets a type, a 0–100 score that traces to its evidence, a level and a flag.

Background

  • Spec 7.1 Confidence Scoring Policy: the score comes from the evidence stored for the device, every part of it traces to stored evidence, and when evidence points to different types, the stronger type wins and only its evidence counts.
  • Spec 7.2: the three identification levels. Spec 7.3: the flagging policy (already in SH-4.1, #39).
  • Spec FR-05, FR-06, FR-08, FR-10, FR-11, OUT-02, OUT-03, DI-03, DI-06.
  • System design section 4 (2.2.4 leaves), section 6 (SH-4, SH-4.1). OOD: DeviceSignature.matches(value), Device.updateIdentification(), updateConfidence(score).
  • Design scope priorities (16.1): "OUI vendor match; confidence score and flag" are Must. The other evidence collectors (mDNS, SSDP, NetBIOS, reverse DNS) are Should and come in M6. So in M3, real scans produce OUI evidence only; signature matching is built and tested with sample evidence, and starts working on real data when the collectors arrive.

Decisions needed (subtask 1, before 2–5 start)

  • Evidence weights. Spec 7.1 lists the evidence types but no weights, and the design leaves them open. Proposal (the OUI weight matches the 20 already used in match_oui):

    Evidence Weight
    OUI (vendor) match 20
    mDNS/DNS-SD name or service 35
    SSDP/UPnP manufacturer or model 35
    NetBIOS/LLMNR name 25
    Reverse DNS hostname 20

    The score is the sum of the kept weights, capped at 100.

  • The identified threshold. Proposal: identified = a signature gave a type and a name, and the score is at least 50; partially identified = the vendor or the type is known; unidentified = neither.

  • A tie between two types. Proposal: neither wins, the type stays "unknown", and the device is flagged. It's better to flag than to guess.

Rules for every subtask

  • No database or network code in the leaves. Each leaf takes data in and returns data. The manager gets the reference rules (3.2.1 find_reference_rules) and the device's stored evidence from its caller.
  • Score from all stored evidence. A device's score is worked out from all its evidence, the new and the stored (ScanStore.evidence_for), not only this scan's. Evidence is never duplicated on rescans (#15), so scanning twice never raises the score.
  • Every point traces to evidence. The score is exactly the sum of the weights of the evidence that was kept, and the result lists which evidence that was.
  • Retired reference data produces no new matches (DI-06). ReferenceRules already leaves retired records out.
  • The type defaults to "unknown" (device type 1, DI-03) when nothing matches or types tie.
  • One shared evidence record. EvidenceItem moves from match_oui.py to backend/services/scan/evidence.py, with the weights table, so every leaf uses the same shape.
  • Unit tests use hand-made evidence and reference rules, with no database or network.

Where the code goes

backend/services/scan/: evidence.py, match_signatures.py, resolve_conflicts.py, calculate_score.py, assign_level.py, identification_manager.py

Subtasks (in order)

  1. Evidence weights and the shared evidence record (spec 7.1)
  2. Match evidence to device signatures (2.2.4.1)
  3. Resolve conflicting evidence (2.2.4.2)
  4. Calculate confidence score (2.2.4.3)
  5. Assign identification level (2.2.4.4)
  6. Identification Manager (2.2.4) and plugging it into the scan

Subtasks 2 to 5 can be worked on at the same time once subtask 1 is merged.

Done when

  • Every device saved by a scan has a type ("unknown" when nothing matches), a 0–100 score and a level
  • Each device's score equals the sum of the weights of its kept evidence, and that evidence is stored
  • When evidence points to two types, the stronger one is assigned and the other's evidence isn't counted
  • Unidentified and partially identified devices are flagged, identified ones aren't, and trusted ones stay unflagged (SH-4.1)
  • Scanning the same network twice doesn't change any score
  • A retired signature no longer matches
  • All unit tests pass without a database or network

Depends on

  • Save Discovered Devices (#36): match_oui (#38), Save Device Record SH-4 (#40), Record Observations and Evidence (#41)
  • Scan Manager (#48), for subtask 6
  • Evaluate Flag SH-4.1 (#39), Network Data (#15) and Reference Data (#16): done

Blocks

Device detail with evidence and score (M4), Detect Alert Events (2.2.5.3, M6), and the evidence collectors (M6), which only need to produce evidence for this manager to use.

Lingua principale
Python
Stelle
1
Fork
1
Nessuna PR unita negli ultimi 30g

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di Bearkat-Professionals/Software-Engineering-Project

Tutte le issue di Bearkat-Professionals/Software-Engineering-Project

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.