netbox-ot 0.3.0__py3-none-any.whl

netbox_ot/__init__.py

@@ -0,0 +1,47 @@
+from netbox.plugins import PluginConfig
+
+__version__ = '0.3.0'
+
+
+class NetBoxOTConfig(PluginConfig):
+    name = 'netbox_ot'
+    verbose_name = 'OT'
+    description = (
+        'OT asset and security register: IEC 62443 zones, conduits and flows, Purdue levels, an access map, '
+        'a zone register and lifecycle checks'
+    )
+    version = __version__
+    author = 'Packetflow'
+    base_url = 'ot'
+    # Tested in CI on 4.7.0, the newest 4.7 release and NetBox's development branch for the next release (weekly)
+    min_version = '4.7.0'
+    max_version = '4.8.99'
+    default_settings = {
+        # Create the "Purdue level" custom field on devices and virtual machines after migrate.
+        'create_custom_fields': True,
+        # The access map lists flows into zones at this Purdue level or below.
+        'access_map_max_level': '2',
+        # A flow not seen for this many days needs attention.
+        'stale_after_days': 90,
+    }
+
+    def ready(self):
+        from django.conf import settings
+        from django.core.exceptions import ImproperlyConfigured
+
+        if 'netbox_iec62443' in settings.PLUGINS:
+            # netbox-ot takes the old plugin's tables over on migrate (adopt.py); both at once would break both
+            raise ImproperlyConfigured(
+                'netbox-ot replaces netbox-iec62443: remove netbox_iec62443 from PLUGINS (and its PLUGINS_CONFIG '
+                'entry; move the settings to netbox_ot), then run migrate.'
+            )
+        super().ready()
+        from django.db.models.signals import post_migrate
+
+        from .customfields import ensure_custom_fields
+        from .upgrade import after_upgrade
+        post_migrate.connect(ensure_custom_fields, sender=self)
+        post_migrate.connect(after_upgrade, sender=self)
+
+
+config = NetBoxOTConfig

netbox_ot/accessmap.py

@@ -0,0 +1,173 @@
+"""
+The access map: every flow into a zone at Purdue level <= N (default 2), i.e. every path to the controllers, with
+its "allowed?" verdict. Not allowed first, then allowed-but-expired, unknown, and allowed. Plus a small
+server-rendered SVG with one arrow per directed zone pair.
+"""
+import datetime
+import math
+from collections import defaultdict
+
+from django.db.models import Case, IntegerField, Q, Value, When
+from django.utils import timezone
+from django.utils.html import escape
+from django.utils.safestring import mark_safe
+from django.utils.translation import gettext as _
+
+from .choices import FlowAllowedChoices, PurdueLevelChoices
+from .models import Flow, Zone, stale_after_days
+
+
+def verdict_order():
+    """0 not allowed, 1 allowed but expired, 2 unknown, 3 allowed."""
+    return Case(
+        When(allowed=FlowAllowedChoices.NO, then=Value(0)),
+        When(allowed=FlowAllowedChoices.YES, expires__lt=timezone.localdate(), then=Value(1)),
+        When(allowed=FlowAllowedChoices.UNKNOWN, then=Value(2)),
+        default=Value(3),
+        output_field=IntegerField(),
+    )
+
+
+def access_map_flows(queryset=None, site=None, max_level=PurdueLevelChoices.LEVEL_2):
+    """Flows into zones at Purdue level <= max_level, from any zone of the site or into one."""
+    levels = PurdueLevelChoices.at_or_below(max_level)
+    qs = (queryset if queryset is not None else Flow.objects.all()).select_related(
+        'source_zone__site', 'destination_zone__site', 'conduit',
+    ).prefetch_related('hops__device', 'hops__virtual_machine', 'hops__tunnel')
+    if site is not None:
+        qs = qs.filter(Q(source_zone__site=site) | Q(destination_zone__site=site))
+    qs = qs.filter(destination_zone__purdue_level__in=levels)
+    return qs.annotate(verdict_order=verdict_order()).order_by(
+        'verdict_order', 'destination_zone__purdue_level', 'destination_zone__name', 'name'
+    )
+
+
+def attention(queryset):
+    """Counts of flows that need a person: allowed but expired, review due, not seen for a while, no conduit."""
+    today = timezone.localdate()
+    stale_before = timezone.now() - datetime.timedelta(days=stale_after_days())
+    return {
+        'expired': queryset.filter(allowed=FlowAllowedChoices.YES, expires__lt=today).count(),
+        'review_due': queryset.filter(review_by__lte=today).count(),
+        'stale': queryset.filter(last_seen__lt=stale_before).count(),
+        'no_conduit': queryset.filter(conduit__isnull=True).count(),
+        'stale_after_days': stale_after_days(),
+    }
+
+
+#
+# SVG diagram: one row per Purdue level (5 at the top, 0 at the bottom), zones as boxes, one arrow per directed
+# zone pair coloured by its worst verdict.
+#
+
+LINE_COLORS = {'no': '#d63939', 'expired': '#d63939', 'unknown': '#f59f00', 'yes': '#2fb344'}
+WORST = ('no', 'expired', 'unknown', 'yes')
+BOX_W, BOX_H, GAP_X, ROW_H, LABEL_W, PAD = 190, 46, 40, 96, 150, 16
+
+
+def _level_rows(zones):
+    order = [None] + [value for value, _label in reversed(PurdueLevelChoices.CHOICES)]
+    labels = {value: str(label).split(' (')[0] for value, label in PurdueLevelChoices.CHOICES}
+    labels[None] = str(_('No level'))
+    rows = []
+    for level in order:
+        members = sorted((z for z in zones if (z.purdue_level or None) == level), key=lambda z: z.name)
+        if members:
+            rows.append((labels[level], members))
+    return rows
+
+
+def _verdict(flow):
+    return 'expired' if flow.is_expired else flow.allowed
+
+
+def access_map_svg(flows, zones=()):
+    """Return an inline SVG (safe string) for the given flows; `zones` adds zones without flows."""
+    flows = list(flows)
+    all_zones = {z.pk: z for z in zones}
+    for f in flows:
+        all_zones.setdefault(f.source_zone_id, f.source_zone)
+        all_zones.setdefault(f.destination_zone_id, f.destination_zone)
+    if not all_zones:
+        return ''
+    rows = _level_rows(all_zones.values())
+    width = LABEL_W + max(len(m) for _l, m in rows) * (BOX_W + GAP_X) + PAD
+    height = len(rows) * ROW_H + PAD
+    pos = {}
+    out, lines, badges = [], [], []
+    for r, (label, members) in enumerate(rows):
+        y = PAD + r * ROW_H
+        out.append(f'<text x="8" y="{y + BOX_H / 2 + 4}" class="lvl">{escape(label)}</text>')
+        out.append(f'<line x1="0" x2="{width}" y1="{y + ROW_H - 25}" y2="{y + ROW_H - 25}" class="sep"/>')
+        for i, z in enumerate(members):
+            x = LABEL_W + i * (BOX_W + GAP_X)
+            pos[z.pk] = (x, y)
+            out.append(
+                f'<a href="{escape(z.get_absolute_url())}"><rect x="{x}" y="{y}" width="{BOX_W}" height="{BOX_H}" '
+                f'rx="4" class="zone"/><text x="{x + BOX_W / 2}" y="{y + BOX_H / 2 + 4}" text-anchor="middle" '
+                f'class="zn">{escape(z.name[:26])}</text></a>'
+            )
+    # One arrow per directed zone pair. Each zone spreads the ends of its arrows across its box, ordered by where
+    # the other zone sits, so arrows do not share a line; the count badge sits just before the arrowhead, in the
+    # gap above or below the destination box, where it cannot cover a zone's name.
+    pairs = {}
+    for f in flows:
+        pairs.setdefault((f.source_zone_id, f.destination_zone_id), []).append(f)
+    ends = defaultdict(list)
+    for src, dst in pairs:
+        ends[src].append(((src, dst), dst))
+        ends[dst].append(((src, dst), src))
+    for zone_pk in ends:
+        ends[zone_pk].sort(key=lambda end: (pos[end[1]][0], pos[end[1]][1]))
+
+    def anchor_x(zone_pk, key):
+        items = [k for k, _other in ends[zone_pk]]
+        n, i = len(items), items.index(key)
+        step = min(28, (BOX_W - 30) / max(n - 1, 1))
+        return pos[zone_pk][0] + BOX_W / 2 + (i - (n - 1) / 2) * step
+
+    for (src, dst), members in pairs.items():
+        (_sx, sy), (_dx, dy) = pos[src], pos[dst]
+        x1, x2 = anchor_x(src, (src, dst)), anchor_x(dst, (src, dst))
+        if sy == dy:  # same row: arc above the boxes
+            y1 = y2 = sy
+            path = f'M{x1},{y1} Q{(x1 + x2) / 2},{sy - 60} {x2},{y2}'
+            lx, ly = (x1 + x2) / 2, sy - 32
+        else:
+            y1 = sy + BOX_H if sy < dy else sy
+            y2 = dy if sy < dy else dy + BOX_H
+            path = f'M{x1},{y1} L{x2},{y2}'
+            length = math.hypot(x2 - x1, y2 - y1) or 1
+            lx, ly = x2 - (x2 - x1) / length * 18, y2 - (y2 - y1) / length * 18
+        worst = min((_verdict(f) for f in members), key=WORST.index)
+        color = LINE_COLORS.get(worst, '#888')
+        dash = ' stroke-dasharray="6 4"' if any(f.remote_access for f in members) else ''
+        title = escape('\n'.join(str(f) for f in members))
+        lines.append(
+            f'<path d="{path}" fill="none" stroke="{color}" stroke-width="2.5"{dash} '
+            f'marker-end="url(#iec-arrow)"><title>{title}</title></path>'
+        )
+        badges.append(
+            f'<circle cx="{lx}" cy="{ly}" r="9" fill="{color}"><title>{title}</title></circle>'
+            f'<text x="{lx}" y="{ly + 4}" text-anchor="middle" class="num">{len(members)}</text>'
+        )
+    aria = escape(_('Access map diagram'))
+    svg = (
+        f'<svg viewBox="0 0 {width} {height}" width="100%" style="max-width:{width}px" role="img" '
+        f'aria-label="{aria}" class="ot-map">'
+        '<defs>'
+        '<marker id="iec-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" '
+        'orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="context-stroke"/></marker>'
+        '</defs>'
+        '<style>.ot-map .zone{fill:var(--tblr-bg-surface,#fff);stroke:rgba(32,107,196,.7);stroke-width:1.5}'
+        '.ot-map .zn{fill:currentColor;font-size:13px;font-weight:600}'
+        '.ot-map .lvl{fill:currentColor;opacity:.7;font-size:12px}'
+        '.ot-map .sep{stroke:currentColor;opacity:.12}'
+        '.ot-map .num{fill:#fff;font-size:11px;font-weight:700}</style>'
+        + ''.join(lines + out + badges) + '</svg>'
+    )
+    return mark_safe(svg)
+
+
+def site_zones(site):
+    return Zone.objects.filter(site=site) if site is not None else Zone.objects.none()

netbox_ot/adopt.py

@@ -0,0 +1,213 @@
+"""
+netbox-ot was called netbox-iec62443 up to 0.2.0 (Django app `netbox_iec62443`). Its first migration takes over
+an installation of the old name in place instead of creating empty tables, so nothing has to be exported or
+re-imported:
+
+- every table, sequence, index and constraint named `netbox_iec62443_*` in the current schema is renamed to
+  `netbox_ot_*`;
+- the content types move to the app label `netbox_ot`, so object IDs, permissions, tags, journal entries, change
+  log, custom fields on the plugin's models, saved filters and bookmarks keep pointing at the same objects;
+- the custom fields `iec62443_purdue_level` and `iec62443_sl_capability` become `ot_purdue_level` and
+  `ot_sl_capability`, values included;
+- dashboard widgets and other user preferences that name a `netbox_iec62443.*` model are rewritten;
+- the old app's rows in `django_migrations` are removed.
+
+The old installation must be at the last migration netbox-iec62443 released (0.2.0); anything else stops the
+migration before it changes a thing. Without a netbox-iec62443 installation the tables are created as usual.
+
+It works on the current schema, so a netbox-branching branch is taken over when the branch is migrated.
+"""
+import logging
+
+from django.db.migrations.operations.base import Operation
+
+OLD_APP = 'netbox_iec62443'
+NEW_APP = 'netbox_ot'
+OLD_LAST_MIGRATION = '0010_drop_single_security_level'
+OLD_PREFIX = f'{OLD_APP}_'
+NEW_PREFIX = f'{NEW_APP}_'
+CUSTOM_FIELD_RENAMES = {
+    'iec62443_purdue_level': 'ot_purdue_level',
+    'iec62443_sl_capability': 'ot_sl_capability',
+}
+
+logger = logging.getLogger('netbox.plugins.netbox_ot')
+
+# Set when this process took over an old installation; post_migrate then rebuilds the search index.
+adopted = False
+
+
+class AdoptionError(RuntimeError):
+    pass
+
+
+def old_installation(cursor):
+    """True when the current schema holds a netbox-iec62443 installation at its last released migration."""
+    cursor.execute('SELECT name FROM django_migrations WHERE app = %s', [OLD_APP])
+    applied = {row[0] for row in cursor.fetchall()}
+    if not applied:
+        return False
+    if OLD_LAST_MIGRATION not in applied:
+        raise AdoptionError(
+            f'netbox-iec62443 is installed but not at its last release (migration {OLD_LAST_MIGRATION}). Upgrade '
+            'it to netbox-iec62443 0.2.0 and run migrate first, then install netbox-ot.'
+        )
+    unknown = sorted(name for name in applied if name > OLD_LAST_MIGRATION)
+    if unknown:
+        raise AdoptionError(
+            f'netbox-iec62443 has migrations applied that no release contains ({", ".join(unknown)}): a development '
+            f'build. Migrate it back first: manage.py migrate {OLD_APP} {OLD_LAST_MIGRATION}'
+        )
+    cursor.execute('SELECT to_regclass(%s)', [f'{OLD_PREFIX}zone'])
+    if cursor.fetchone()[0] is None:
+        raise AdoptionError(f'django_migrations lists {OLD_APP} but its tables are missing from the current schema.')
+    return True
+
+
+def rename_database_objects(cursor, quote, old_prefix=OLD_PREFIX, new_prefix=NEW_PREFIX):
+    """Rename the tables, sequences, indexes and constraints in the current schema named old_prefix*."""
+    def new_name(name):
+        return new_prefix + name[len(old_prefix):]
+
+    like = old_prefix.replace('_', r'\_') + '%'
+    # Constraints without an index of their own (foreign keys, checks, not-null); index-backed ones (primary key,
+    # unique, exclusion) are renamed with their index below.
+    cursor.execute(
+        """
+        SELECT t.relname, c.conname FROM pg_constraint c
+        JOIN pg_class t ON t.oid = c.conrelid
+        JOIN pg_namespace n ON n.oid = t.relnamespace
+        WHERE n.nspname = current_schema() AND t.relname LIKE %s AND c.conname LIKE %s
+          AND c.contype NOT IN ('p', 'u', 'x')
+        """,
+        [like, like],
+    )
+    for table, constraint in cursor.fetchall():
+        cursor.execute(
+            f'ALTER TABLE {quote(table)} RENAME CONSTRAINT {quote(constraint)} TO {quote(new_name(constraint))}'
+        )
+    counts = {}
+    for relkind, statement in (('i', 'ALTER INDEX'), ('S', 'ALTER SEQUENCE'), ('r', 'ALTER TABLE')):
+        cursor.execute(
+            """
+            SELECT c.relname FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+            WHERE n.nspname = current_schema() AND c.relkind = %s AND c.relname LIKE %s
+            """,
+            [relkind, like],
+        )
+        names = [row[0] for row in cursor.fetchall()]
+        for name in names:
+            cursor.execute(f'{statement} {quote(name)} RENAME TO {quote(new_name(name))}')
+        counts[relkind] = len(names)
+    return counts
+
+
+def rename_custom_fields(cursor, quote, apps):
+    for old, new in CUSTOM_FIELD_RENAMES.items():
+        cursor.execute('SELECT id FROM extras_customfield WHERE name = %s', [old])
+        old_row = cursor.fetchone()
+        cursor.execute('SELECT id FROM extras_customfield WHERE name = %s', [new])
+        new_row = cursor.fetchone()
+        if old_row and new_row:
+            logger.warning('Custom field %s already exists; %s left as it is', new, old)
+            continue
+        if old_row:
+            cursor.execute('UPDATE extras_customfield SET name = %s WHERE id = %s', [new, old_row[0]])
+        elif not new_row:
+            continue
+        # Without an old row the field was renamed already: a netbox-branching branch migrates after main, and
+        # custom field definitions live in main only, while the branch has its own copy of the objects' values.
+        row = old_row or new_row
+        field = apps.get_model('extras', 'CustomField')._meta.get_field('object_types')
+        cursor.execute(
+            f"""
+            SELECT ct.app_label, ct.model FROM {quote(field.m2m_db_table())} cot
+            JOIN django_content_type ct ON ct.id = cot.{quote(field.m2m_reverse_name())}
+            WHERE cot.{quote(field.m2m_column_name())} = %s
+            """,
+            [row[0]],
+        )
+        for app_label, model in cursor.fetchall():
+            try:
+                table = apps.get_model(app_label, model)._meta.db_table
+            except LookupError:
+                continue
+            cursor.execute(
+                f"""
+                UPDATE {quote(table)}
+                SET custom_field_data = (custom_field_data - %s) || jsonb_build_object(%s, custom_field_data -> %s)
+                WHERE custom_field_data ? %s
+                """,
+                [old, new, old, old],
+            )
+
+
+def adopt(schema_editor, apps):
+    global adopted
+    quote = schema_editor.quote_name
+    with schema_editor.connection.cursor() as cursor:
+        counts = rename_database_objects(cursor, quote)
+        cursor.execute(
+            'UPDATE django_content_type SET app_label = %s WHERE app_label = %s', [NEW_APP, OLD_APP]
+        )
+        rename_custom_fields(cursor, quote, apps)
+        cursor.execute(
+            """
+            UPDATE users_userconfig SET data = replace(data::text, %s, %s)::jsonb
+            WHERE data::text LIKE %s
+            """,
+            [f'"{OLD_APP}.', f'"{NEW_APP}.', f'%"{OLD_APP}.%'],
+        )
+        cursor.execute('DELETE FROM django_migrations WHERE app = %s', [OLD_APP])
+    adopted = True
+    logger.info(
+        'Took over the netbox-iec62443 installation: %s tables, %s sequences, %s indexes renamed',
+        counts['r'], counts['S'], counts['i'],
+    )
+
+
+class AdoptOrCreate(Operation):
+    """Take over a netbox-iec62443 installation (see the module docstring), or run `operations` to create the
+    tables. The migration state is always that of `operations`."""
+
+    reversible = True
+
+    def __init__(self, operations):
+        self.operations = operations
+
+    def deconstruct(self):
+        return self.__class__.__qualname__, [], {'operations': self.operations}
+
+    def state_forwards(self, app_label, state):
+        for operation in self.operations:
+            operation.state_forwards(app_label, state)
+
+    def database_forwards(self, app_label, schema_editor, from_state, to_state):
+        with schema_editor.connection.cursor() as cursor:
+            take_over = old_installation(cursor)
+        if take_over:
+            adopt(schema_editor, from_state.apps)
+            return
+        for operation in self.operations:
+            state = from_state.clone()
+            operation.state_forwards(app_label, state)
+            operation.database_forwards(app_label, schema_editor, from_state, state)
+            from_state = state
+
+    def database_backwards(self, app_label, schema_editor, from_state, to_state):
+        # As SeparateDatabaseAndState does it: undo the operations last to first, each between its own states.
+        before = {}
+        for index, operation in enumerate(self.operations):
+            before[index] = to_state
+            to_state = to_state.clone()
+            operation.state_forwards(app_label, to_state)
+        for index in reversed(range(len(self.operations))):
+            from_state, to_state = to_state, before[index]
+            self.operations[index].database_backwards(app_label, schema_editor, from_state, to_state)
+
+    def describe(self):
+        return 'Take over a netbox-iec62443 installation, or create the tables'
+
+    @property
+    def migration_name_fragment(self):
+        return 'initial'