lyss 0.8.0__py3-none-any.whl

lyss/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026 Mouad Lyaazale. Additional terms (author attribution, names): see NOTICE.
+"""LYSS: Lyaazale Switch Security."""
+
+PROJECT_NAME = "LYSS"
+PROJECT_LONG_NAME = "Lyaazale Switch Security"
+__version__ = "0.8.0"

lyss/__main__.py

@@ -0,0 +1,248 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026 Mouad Lyaazale. Additional terms (author attribution, names): see NOTICE.
+"""Command line.
+
+  python -m lyss audit --vendor <adapter> <file-or-folder>   assess saved configurations
+  python -m lyss collect [--only id ...]                     collect + audit inventory devices
+  python -m lyss oxidized --url http://oxidized:8888         assess the configs backed up by Oxidized
+  python -m lyss import-legacy <inventory.csv> <cred-dir>    import devices + PowerShell cred files
+  python -m lyss ui [--port 8765]                            start the local web interface
+  python -m lyss sim [--lab demo] [--base-port 2201]         simulated switches over SSH (127.0.0.1)
+  python -m lyss demo [--port 8766] [--reset]                web interface on the simulated demo lab
+"""
+
+import argparse
+import csv
+import json
+import sys
+import time
+from dataclasses import asdict
+from pathlib import Path
+
+from . import PROJECT_LONG_NAME, PROJECT_NAME, __version__
+from .engine import audit, conformance, load_spec
+
+ICONS = {"pass": "PASS", "fail": "FAIL", "unknown": "????", "not_applicable": "n/a "}
+
+
+def print_text(name: str, findings, summary) -> None:
+    print(f"\n=== {name}  ->  {PROJECT_NAME} Level {summary['achieved_level']} "
+          f"(pass {summary['pass']}, fail {summary['fail']}, unknown {summary['unknown']})")
+    for f in findings:
+        print(f"  [{ICONS[f.verdict]}] {f.control_id}  {f.title}")
+        for e in f.evidence[:3]:
+            print(f"           evidence: {e}")
+        if f.note:
+            print(f"           note: {f.note}")
+        if f.remediation:
+            for line in f.remediation.splitlines():
+                print(f"           fix> {line}")
+
+
+def cmd_audit(args) -> int:
+    # a device = <name>.cfg (configuration) + optional <name>.state.txt (collected device state)
+    files = sorted(args.path.glob("*.cfg")) if args.path.is_dir() else [args.path]
+    results = []
+    for path in files:
+        state_file = path.with_name(path.stem + ".state.txt")
+        state_text = state_file.read_text(encoding="utf-8", errors="replace") if state_file.exists() else ""
+        findings = audit(path.read_text(encoding="utf-8", errors="replace"), args.vendor, args.level, state_text)
+        summary = conformance(findings)
+        if args.json:
+            results.append({"device": path.name, "vendor": args.vendor,
+                            "summary": summary, "findings": [asdict(f) for f in findings]})
+        else:
+            print_text(path.name, findings, summary)
+
+    if args.json:
+        json.dump({"tool": PROJECT_NAME, "version": __version__,
+                   "spec_version": load_spec()["spec_version"], "results": results},
+                  sys.stdout, indent=2, ensure_ascii=False)
+    return 0
+
+
+def cmd_collect(args) -> int:
+    from . import inventory, scan
+
+    ids = args.only or [d["id"] for d in inventory.load_devices()]
+    started = time.monotonic()
+    # --scheduled: run by cron / Task Scheduler, counts as an automatic backup (LYSS-BKP-001)
+    if not scan.start(ids, trigger="schedule" if args.scheduled else "cli"):
+        print("a scan is already running")
+        return 1
+    shown = {}
+    while True:
+        job = scan.current_job()
+        for device_id, item in job["items"].items():
+            if shown.get(device_id) != item["status"] and item["status"] in ("done", "error"):
+                print(f"{device_id:18} {item['status']:6} {item['message']}")
+            shown[device_id] = item["status"]
+        if job["finished"]:
+            break
+        time.sleep(0.5)
+    for notice in job.get("notices", []):
+        print(notice)
+    print(f"total {time.monotonic() - started:.0f}s")
+    return 1 if any(i["status"] == "error" for i in job["items"].values()) else 0
+
+
+def cmd_oxidized(args) -> int:
+    """Assess the configurations backed up by Oxidized (REST API), without connecting to the switches."""
+    import os
+
+    from . import events, oxidized
+    password = os.environ.get("LYSS_OXIDIZED_PASSWORD", "")  # never on the command line
+    with oxidized.client(args.url, args.user or "", password, not args.insecure) as http:
+        results, skipped = oxidized.assess_all(http, args.level, args.only)
+    if args.json:
+        json.dump({"tool": PROJECT_NAME, "version": __version__, "source": "oxidized",
+                   "spec_version": load_spec()["spec_version"], "results": results, "skipped": skipped},
+                  sys.stdout, indent=2, ensure_ascii=False)
+    else:
+        from .engine import Finding
+        for r in results:
+            print_text(f"{r['device']} ({r['host']}, {r['vendor']}, from Oxidized)",
+                       [Finding(**f) for f in r["findings"]], r["summary"])
+        for s in skipped:
+            print(f"\n--- {s['device']}: skipped, {s['reason']}")
+        print(f"\n{len(results)} switch(es) assessed from Oxidized, {len(skipped)} skipped.")
+    if args.events:
+        cfg = events.settings()
+        if not (cfg.get("host") or cfg.get("file")):
+            print("SIEM events: configure a syslog server or an events file in Settings first.", file=sys.stderr)
+            return 2
+        sent = events.send(events.wrap([e for r in results for e in events.result_events(
+            {"device": r["device"], "host": r["host"], "site": r["group"]}, r, {}, cfg.get("findings", "all"),
+            "oxidized")]), cfg)
+        print(f"{sent} event(s) sent to the SIEM.", file=sys.stderr)
+    return 0
+
+
+def cmd_import_legacy(args) -> int:
+    """Devices from a CSV (name,vendor,ip,cred) + PowerShell Export-Clixml credential files.
+    The DPAPI-protected password is copied as-is: it is never decrypted during the import."""
+    from . import inventory, vault
+
+    devices = inventory.load_devices()
+    for row in csv.DictReader(args.csv.open(encoding="utf-8")):
+        user, protected = vault.read_ps_credential(args.cred_dir / row["cred"])
+        record = {"id": row["name"], "host": row["ip"], "port": 22, "vendor": row["vendor"],
+                  "username": user, "via_jump": args.via_jump, "secret": protected}
+        devices = [d for d in devices if d["id"] != record["id"]] + [record]
+        print(f"imported {row['name']}")
+    inventory._write(inventory.DEVICES_FILE, sorted(devices, key=lambda d: d["id"]))
+    return 0
+
+
+def cmd_ui(args) -> int:
+    import os
+
+    import uvicorn
+
+    from . import scheduler
+    from .web.app import app
+    if args.host not in ("127.0.0.1", "localhost", "::1") and os.environ.get("LYSS_ALLOW_REMOTE") != "1":
+        # inside a container the UI must listen on all interfaces; publish the port on 127.0.0.1
+        # only, or put an HTTPS reverse proxy in front: the UI itself speaks plain HTTP
+        print("Refusing to listen on a non-local address without LYSS_ALLOW_REMOTE=1.")
+        return 2
+    scheduler.start_background()
+    print(f"{PROJECT_LONG_NAME} UI on http://{args.host}:{args.port}  (Ctrl+C to stop)")
+    uvicorn.run(app, host=args.host, port=args.port, log_level="warning", server_header=False)
+    return 0
+
+
+def cmd_sim(args) -> int:
+    import tempfile
+
+    from .sim import Simulator, load_lab
+    lab = load_lab(args.lab)
+    keys = args.keys_dir or Path(tempfile.gettempdir()) / "lyss-sim-keys" / lab.name
+    sim = Simulator(lab, base_port=args.base_port, keys_dir=keys)
+    try:
+        sim.start()
+    except OSError as exc:
+        print(f"Cannot open the simulator ports from {args.base_port}: {exc}")
+        return 2
+    print(f"{PROJECT_NAME} simulator - lab '{lab.name}' ({lab.organization}, fictitious devices)")
+    for d in sim.describe():
+        print(f"  {d['id']:<12} {d['platform']:<12} {d['hostname']:<14} {d['model']:<16} 127.0.0.1:{d['port']}")
+    print(f"  SSH login: {lab.credentials['username']} / {lab.credentials['password']}   (Ctrl+C to stop)")
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        sim.stop()
+    return 0
+
+
+def cmd_demo(args) -> int:
+    from .sim import demo
+    try:
+        return demo.run(args.lab, args.data_dir, args.port, args.base_port, args.reset, args.open)
+    except ValueError as exc:
+        print(exc)
+        return 2
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(prog="lyss", description=f"{PROJECT_LONG_NAME} {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    a = sub.add_parser("audit", help="assess saved configuration files")
+    a.add_argument("--vendor", required=True, help="adapter name, e.g. cisco_ios, cisco_sb, hp_procurve, mikrotik, sonic")
+    a.add_argument("--level", type=int, default=1, help="highest level to assess (default 1)")
+    a.add_argument("--json", action="store_true", help="output JSON instead of text")
+    a.add_argument("path", type=Path)
+    a.set_defaults(func=cmd_audit)
+
+    c = sub.add_parser("collect", help="collect and audit inventory devices (read-only)")
+    c.add_argument("--only", nargs="*", help="device ids (default: all)")
+    c.add_argument("--scheduled", action="store_true",
+                   help="run from cron / Task Scheduler: counts as an automatic configuration backup")
+    c.set_defaults(func=cmd_collect)
+
+    o = sub.add_parser("oxidized", help="assess the configurations backed up by Oxidized (no SSH to the switches)")
+    o.add_argument("--url", required=True, help="Oxidized REST API, e.g. http://oxidized:8888")
+    o.add_argument("--user", help="HTTP basic auth user (password in LYSS_OXIDIZED_PASSWORD)")
+    o.add_argument("--insecure", action="store_true", help="do not verify the TLS certificate")
+    o.add_argument("--level", type=int, default=2, help="highest level to assess (default 2)")
+    o.add_argument("--only", nargs="*", help="node names (default: all supported nodes)")
+    o.add_argument("--json", action="store_true", help="output JSON instead of text")
+    o.add_argument("--events", action="store_true", help="also send SIEM events (Settings > SIEM events)")
+    o.set_defaults(func=cmd_oxidized)
+
+    i = sub.add_parser("import-legacy", help="import devices from CSV + PowerShell cred files")
+    i.add_argument("csv", type=Path)
+    i.add_argument("cred_dir", type=Path)
+    i.add_argument("--via-jump", action="store_true", help="reach these devices through the jump host")
+    i.set_defaults(func=cmd_import_legacy)
+
+    u = sub.add_parser("ui", help="start the local web interface")
+    u.add_argument("--port", type=int, default=8765)
+    u.add_argument("--host", default="127.0.0.1", help="listen address (non-local needs LYSS_ALLOW_REMOTE=1)")
+    u.set_defaults(func=cmd_ui)
+
+    s = sub.add_parser("sim", help="run simulated switches (fictitious lab) over SSH on 127.0.0.1")
+    s.add_argument("--lab", default="demo", help="lab name or folder (default: demo)")
+    s.add_argument("--base-port", type=int, default=2201, help="SSH port of the first switch (default 2201)")
+    s.add_argument("--keys-dir", type=Path, help="where the simulated host keys are kept")
+    s.set_defaults(func=cmd_sim)
+
+    d = sub.add_parser("demo", help="web interface on the simulated demo lab (separate data directory)")
+    d.add_argument("--lab", default="demo")
+    d.add_argument("--port", type=int, default=8766, help="web interface port (default 8766)")
+    d.add_argument("--base-port", type=int, default=2201, help="SSH port of the first simulated switch")
+    d.add_argument("--data-dir", type=Path, help="demo data directory (default: <temp>/lyss-demo)")
+    d.add_argument("--reset", action="store_true", help="start again from an empty demo directory")
+    d.add_argument("--open", action="store_true", help="open the browser")
+    d.set_defaults(func=cmd_demo)
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

lyss/_bundled/adapters/cisco_ios.yaml

@@ -0,0 +1,260 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026 Mouad Lyaazale. Additional terms (author attribution, names): see NOTICE.
+# LYSS adapter: Cisco IOS / IOS-XE (Catalyst).
+# Rule forms:
+#   {line: R}                       true if any config line (top level or inside a block) matches R
+#   {block: H, line: R}             true if any block whose header matches H contains a line matching R
+#   {block: H, every_contains: R}   true if at least one H block exists and every one contains R
+#   add where: W to a block rule    only consider H blocks that contain a line matching W
+#   add where_not: W to a block rule  only consider H blocks with no line matching W
+#   add gt: N to a line rule        true only if the first regex group, as a number, is > N
+#   {state: R, section: S}          true if a line of collected state section S matches R
+#   add absent: true to a state rule  true if section S was collected and no line matches R
+#   {ports_in_both: [A, B]}         true if some port (group 1) appears in both state tables A and B
+#   {captures_in_both: [A, B]}      true if a value (group 1) is captured by both A and B, where a
+#                                   capture is {line: R}, {block: H, where: W} (group 1 of the header),
+#                                   {block: H, where: W, line: R}, {untagged_access_vlans: true}
+#                                   (port-list platforms) or a list of these
+# Per control: fail_if_any -> fail; firmware -> data/firmware.yaml; pass_if_all / pass_if_any -> pass;
+# else `otherwise`. A state rule never matches when that state was not collected.
+adapter: cisco_ios
+spec_version: "0.5.0-draft"
+platform: Cisco IOS / IOS-XE
+status: draft, validated on Catalyst C1000 15.2(7)E (real devices, 2026-11)
+
+facts:
+  model:   {section: show inventory, line: '^PID:\s*(\S+)'}
+  version: {section: show version, line: 'Version ([^,\s]+)'}
+
+checks:
+
+  # ---------------- Level 1 ----------------
+
+  LYSS-MGMT-001:
+    fail_if_any:
+      - {block: '^line vty', line: '^transport input .*\b(telnet|all)\b'}
+      - {state: ':23\s.*LISTEN', section: show control-plane host open-ports}
+    pass_if_all:
+      - {block: '^line vty', every_contains: '^transport input (ssh|none)\s*$'}
+    otherwise: fail
+    note: Without an explicit "transport input ssh", many IOS versions accept Telnet on vty lines.
+    remediation: |
+      line vty 0 15
+       transport input ssh
+
+  LYSS-MGMT-002:
+    fail_if_any:
+      - {state: '^SSH-1\.', section: ssh banner}
+    pass_if_any:
+      - {line: '^ip ssh version 2\s*$'}
+      - {state: '^SSH-2\.0-', section: ssh banner}
+    otherwise: fail
+    note: Without "ip ssh version 2", IOS runs SSH 1.99 and accepts SSHv1 clients.
+    remediation: |
+      ip ssh version 2
+
+  LYSS-MGMT-003:
+    fail_if_any:
+      - {line: '^ip http server\s*$'}
+      - {state: ':80\s.*LISTEN', section: show control-plane host open-ports}
+    otherwise: pass
+    remediation: |
+      no ip http server
+      ip http secure-server   ! only if the web UI is really needed
+
+  LYSS-MGMT-004:
+    fail_if_any:
+      - {block: '^line (con|vty)', line: '^exec-timeout 0( 0)?\s*$'}
+      - {block: '^line (con|vty)', line: '^exec-timeout (\d+)', gt: 10}
+    otherwise: pass
+    note: IOS default is 10 minutes when exec-timeout is not set.
+    remediation: |
+      line con 0
+       exec-timeout 10 0
+      line vty 0 15
+       exec-timeout 10 0
+
+  LYSS-AUTH-001:
+    fail_if_any:
+      - {line: '(?i)^snmp-server community (public|private)\b'}
+    otherwise: pass
+    remediation: |
+      no snmp-server community public
+      no snmp-server community private
+      ! then configure SNMPv3 (LYSS-AUTH-011)
+
+  LYSS-AUTH-002:
+    fail_if_any:
+      - {line: '^enable password\b'}
+      # type 5 = MD5-crypt, type 4 = flawed unsalted SHA-256: not accepted (cracked quickly)
+      - {line: '^enable (algorithm-type md5 )?secret [45] '}
+      - {line: '^username \S+ (.* )?privilege 15 (.* )?(secret [45]|password) '}
+    pass_if_any:
+      - {line: '^enable (algorithm-type (scrypt|sha256) )?secret [89] '}
+      # no enable credential at all: privilege 15 only through local accounts with a strong hash
+      - {line: '^username \S+ (.* )?privilege 15 (.* )?secret [89] ', say: 'no enable credential; privileged access only through local accounts hashed with scrypt / PBKDF2-SHA-256 (secret 9 / 8)'}
+    otherwise: unknown
+    note: Accepted hashes are type 9 (scrypt) and type 8 (PBKDF2-SHA-256); without an enable credential, privilege 15 must come from AAA or such local users.
+    remediation: |
+      no enable password
+      enable algorithm-type scrypt secret <new-secret>
+
+  LYSS-AUTH-003:
+    fail_if_any:
+      - {line: '^username \S+ .*\bpassword\b'}
+    otherwise: pass
+    note: 'A "username ... password" line is stored cleartext (type 0) or reversible (type 7); use "secret".'
+    remediation: |
+      username <name> privilege 15 algorithm-type scrypt secret <new-secret>
+      ! then remove the old "username <name> password" line
+
+  LYSS-AUTH-004:
+    fail_if_any:
+      - {block: '^(radius|tacacs) server', line: '^key (0 )?(?!(6|7) )\S'}
+      - {line: '^(radius|tacacs)-server (.* )?key (0 )?(?!(6|7) )\S'}
+    otherwise: pass
+    note: Type 7 is not cleartext but is reversible; prefer type 6 (AES with a device master key).
+    remediation: |
+      key config-key password-encrypt <master-key>
+      password encryption aes
+      ! then rotate the shared key on the switch AND on the RADIUS server (NPS)
+
+  LYSS-VULN-001:
+    firmware: true
+    otherwise: unknown
+    note: Model/firmware not collected, or platform not yet in data/firmware.yaml.
+    remediation: |
+      ! upgrade to the latest release of the train named in the evidence
+      ! (Catalyst 1000: 15.2(7)E14 or later; security fixes until 2028-04-30)
+      ! until then, restrict SNMP and management access to the admin network (LYSS-MGMT-010)
+
+  LYSS-BKP-001:
+    backup: true   # vendor-neutral: evaluated from the LYSS configuration archive / attestation
+    otherwise: unknown
+    note: No backup evidence yet. Enable scheduled scans, or attest the external backup system on the switch page.
+    remediation: |
+      ! Settings > Scheduled scans (LYSS keeps every configuration version), or
+      ! attest the external backup (Oxidized, RANCID...) on the switch page.
+
+  # ---------------- Level 2 ----------------
+
+  LYSS-AUTH-010:
+    fail_if_any:
+      # the default list (used by vty lines without "login authentication") must start with AAA
+      - {line: '^aaa authentication login default (?!group\b)\S'}
+      # a named list used by a vty line must start with AAA too
+      - captures_in_both:
+          - {block: '^line vty', line: '^login authentication (\S+)'}
+          - {line: '^aaa authentication login (\S+) (?!group\b)\S'}
+    pass_if_all:
+      - {line: '^aaa new-model'}
+      - {line: '^aaa authentication login \S+ group \S+'}
+    otherwise: fail
+    note: Every login list used for remote access must start with "group <radius/tacacs>"; local only after it.
+    remediation: |
+      aaa new-model
+      aaa authentication login default group <radius-group> local
+      aaa authorization exec default group <radius-group> local
+
+  LYSS-AUTH-011:
+    fail_if_any:
+      - {line: '^snmp-server community '}
+      - {line: '^snmp-server group \S+ v(1|2c?)\b'}
+      # SNMPv3 below authPriv: noauth (noAuthNoPriv) or auth (authNoPriv)
+      - {line: '^snmp-server group \S+ v3 (noauth|auth)\b'}
+    otherwise: pass
+    remediation: |
+      no snmp-server community <name>
+      snmp-server group LYSS v3 priv
+      snmp-server user <user> LYSS v3 auth sha <pw> priv aes 128 <pw>
+
+  LYSS-MGMT-010:
+    pass_if_all:
+      - {block: '^line vty', every_contains: '^access-class \S+ in'}
+    otherwise: fail
+    remediation: |
+      ip access-list standard MGMT
+       permit <admin-subnet> <wildcard>
+      line vty 0 15
+       access-class MGMT in
+
+  LYSS-MGMT-011:
+    fail_if_any:
+      - {block: '^interface Vlan1$', line: '^ip address (\d|dhcp)'}
+      # an access port in the management VLAN puts user traffic next to the management address
+      - captures_in_both:
+          - {block: '^interface Vlan(\d+)$', where: '^ip address \d'}
+          - {block: '^interface \S*Ethernet', where: '^switchport mode access', line: '^switchport access vlan (\d+)'}
+    pass_if_any:
+      - {block: '^interface Vlan(?!1$)\d+$', line: '^ip address \d'}
+    otherwise: unknown
+    remediation: |
+      interface Vlan<mgmt-vlan>
+       ip address <ip> <mask>
+      interface Vlan1
+       no ip address
+       shutdown
+
+  LYSS-MGMT-012:
+    pass_if_all:
+      - {line: '^banner (login|motd) '}
+      - {line: '(?i)authori[sz]ed'}
+    otherwise: fail
+    note: The login or MOTD banner (shown before authentication) must state the authorized-use restriction.
+    remediation: |
+      banner login ^Authorized access only. Activity is logged.^
+
+  LYSS-MGMT-013:
+    fail_if_any:
+      - {state: '^kex: .*(sha1|group1\b)', section: ssh negotiated}
+      - {state: '^cipher: .*(cbc|3des|arcfour|blowfish)', section: ssh negotiated}
+      - {state: '^hostkey: (ssh-rsa|ssh-dss)\s*$', section: ssh negotiated}
+    pass_if_any:
+      - {state: '^kex: ', section: ssh negotiated}
+    otherwise: unknown
+    note: Needs the negotiated SSH algorithms (collector).
+    remediation: |
+      ip ssh dh min size 2048
+      ip ssh server algorithm encryption aes256-ctr aes192-ctr aes128-ctr
+      ip ssh server algorithm mac hmac-sha2-256 hmac-sha2-512
+      ! if the image offers no SHA-2 key exchange, upgrade IOS (check "ip ssh server algorithm kex ?")
+
+  LYSS-LOG-010:
+    fail_if_any:
+      - {line: '^no logging on\b', say: 'logging is disabled globally ("no logging on"): nothing reaches the syslog hosts'}
+    pass_if_any:
+      - {line: '^logging (host )?\d+\.\d+\.\d+\.\d+'}
+    otherwise: fail
+    remediation: |
+      logging host <siem-ip>
+      logging trap informational
+
+  LYSS-LOG-011:
+    fail_if_any:
+      - {state: '(?i)\bunsynchroni[sz]ed\b', section: show ntp status}
+    pass_if_any:
+      - {line: '^ntp server '}
+    otherwise: fail
+    note: Synchronization is checked with "show ntp status"; without device state, a configured server passes.
+    remediation: |
+      ntp server <ntp-ip>
+
+  LYSS-ACC-010:
+    fail_if_any:
+      - {state: '\bnotconnect\b', section: show interfaces status}
+    pass_if_any:
+      - {state: '.', section: show interfaces status}
+    otherwise: unknown
+    note: Needs "show interfaces status" (notconnect = enabled but unused; disabled = shut).
+    remediation: |
+      interface range <unused-ports>
+       shutdown
+       switchport access vlan <parking-vlan>
+
+  LYSS-ACC-011:
+    pass_if_any:
+      - {line: '^spanning-tree portfast (edge )?bpduguard default'}
+      - {block: '^interface \S*Ethernet', where: '^switchport mode access', every_contains: '^spanning-tree bpduguard enable'}
+    otherwise: fail
+    remediation: |
+      spanning-tree portfast edge bpduguard default