SUBTASK #63: Identification Manager (2.2.4) and plugging it into the scan

Open
  • Is something wrong?
#69 0 comments 0 reactions 1 assignee View on GitHub

Maintainers usually reply within 1 day

@PavlockBlaine03 is already working on this.

Since Oct 30, 2026.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
48/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
python
Domain
backend

Research direction

Read the referenced leaves #64–#68, Evaluate Flag #39, and the scan save path in Scan Manager #48 / SH-4 #40; inspect match_oui.py and the existing stores. Implement and test identify in backend/services/scan/identification_manager.py, then add the scan integration and checkpoint script described in the issue. Done means repeated scans are idempotent, retired signatures stop contributing, user-entered names survive rescans, and the checkpoint shows each device's identification fields.

Written by the indexing model from the issue text.

Description

backend Medium Priority subtask

What to do

Build the Identification Manager (2.2.4), which runs the four leaves in order for one device: match OUI and signatures, resolve conflicts, calculate the score, assign the level, then evaluate the flag (SH-4.1). Then plug it into the scan in place of M2's provisional "OUI match = partial" rule, so each saved device gets its type, vendor, score, level and flag from its evidence.

Background

  • System design section 4: the Scan Manager runs discovery (2.2.2), evidence collection (2.2.3), identification (2.2.4) and recording (2.2.5). 2.2.4 gets the reference rules from the manager and calls no sibling.
  • Spec 7.1: the score comes from all the evidence stored for the device. Spec 7.3: the flag follows the level, trust and whether the device is new.
  • The leaves are #64 to #68, and SH-4.1 is evaluate_flag (#39).
  • Data access is ready: find_reference_rules (3.2.1, active records only), ScanStore.evidence_for and add_evidence (no duplicates on rescans), and DeviceStore.store, all with an optional unit for one transaction (#15, #16).
  • Rules are in #63.

Steps

  • identification_manager.py:
    • IdentificationResult record: the Identification (#68), flagged, and new_evidence (the evidence to save for this scan)
    • identify(host, collected, stored_evidence, rules, trusted, is_new_device) -> IdentificationResult, pure:
      • OUI: match_oui using a lookup built from rules (this replaces the load_oui_lookup TODO in match_oui.py)
      • Signatures: match_signatures(collected, rules.signatures). With no collectors yet (M6), collected is empty in real scans.
      • Stored evidence: turned back into matches using rules.signatures by signature_id. Evidence whose signature is now retired stays stored but isn't counted (it can't produce new matches, DI-06).
      • New and stored evidence combined without duplicates (same type, value and signature), then resolve_conflicts → calculate_score → assign_level → evaluate_flag
  • Plug it into the scan's save path (Scan Manager #48 / SH-4 #40), for each host, in one unit of work:
    • Find the device by MAC and load its stored evidence (none for a new device)
    • Call identify with the reference rules loaded once per scan
    • SH-4 saves the device with the type, vendor, score and flag; then 2.2.5.2 saves the observation and the new evidence
    • A scan sets device_name and model only when they're empty, so a name a user typed is never replaced
    • Remove the provisional "OUI match = partial" rule and its comments
  • Unit tests for identify, with hand-made rules and evidence:
    • OUI only: partially identified, score 20, flagged
    • OUI plus a strong signature match: identified, not flagged
    • Stored evidence counts with new evidence; the same evidence in both counts once
    • Stored evidence of a retired signature isn't counted
    • A trusted, already-known device stays unflagged; the same device under a new MAC is flagged
  • Integration tests against the test database:
    • Scanning the same hosts twice leaves every score, type and flag unchanged, and adds no evidence
    • Retiring a signature, then scanning again: the device no longer gets that type
    • A user's device name survives a rescan
  • Checkpoint script, python -m backend.services.scan.check_identification: after a scan of the test database, print each device's MAC, vendor, type, score, level and flag

Where

  • backend/services/scan/identification_manager.py
  • The scan's save path (Scan Manager #48 / SH-4 #40) and match_oui.py (small changes)
  • tests/services/scan/test_identification_manager.py, and an integration test next to the Scan Manager's

Done when

  • The checkpoint script, run after a real scan, shows every device with a type, vendor, score, level and flag
  • All of #63's "Done when" items pass
  • All unit tests pass without a database or network

Depends on

  • #64 to #68 (the evidence record and the four leaves) and Evaluate Flag SH-4.1 (#39)
  • Save Device Record SH-4 (#40), Record Observations and Evidence (#41) and Scan Manager (#48)
Dominant language
Python
Stars
1
Forks
1
Avg merge
9h 31m
Merged PRs (30d)
36

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Bearkat-Professionals/Software-Engineering-Project

All issues in Bearkat-Professionals/Software-Engineering-Project

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.