NIDS Assignment Content Guide
How to use this page
Start from How to Create a NIDS Assignment, which covers the prerequisites and the four steps that take an assignment from an empty repository to a listing on the Assignments page. That page summarizes what an assignment contains; this page is the long form of that summary, and is meant to be worked through before you write anything.
The three pages divide like this:
| Page | Answers |
|---|---|
| How to Create a NIDS Assignment | What are the steps? |
| NIDS Assignment Planning Guide | What should I sketch before I start? |
| This page | What goes in it, and why? |
| NIDS Assignment Style Guide | How is each file written? We expect this to be used by an agent. |
Four questions decide almost everything the repository contains. Answer them in order — each one narrows the next.
What the Assignment Introduces
Every assignment exists to introduce something the student has not seen before. Before writing anything, name what that is. It falls into four categories, and most assignments introduce something in more than one:
| Category | What it means | Examples from published assignments |
|---|---|---|
| Dataset | the measurement data itself | Router-level topology inferred from traceroute, with its alias-resolution, ASN, and geolocation annotations (nids-itdk) · Daily active DNS measurements across hundreds of millions of domains (nids-dns-ecosystem) |
| Tool | a query language, library, or platform | Cypher, the query language of the Neo4j graph database (nids-iyp) · dpkt for parsing packets and pyarrow for writing Parquet (nids-telescope-traffic) · PySpark with the S3A connector, reading partitioned Parquet from an object store (nids-dns-ecosystem) |
| Practice | a way of working | Building flow records from raw packet captures in a memory-efficient streaming pass (nids-telescope-traffic) · Porting an interactive prototype into a Slurm batch array to cover a longer period (nids-ucsdnt-expanse) · Prototyping a query on a small TLD before scaling it to a large one (nids-dns-ecosystem) |
| Idea | a concept that outlives the dataset | Provenance — independent sources disagree, so record every source’s claim instead of flattening them into one value (nids-iyp) · Market concentration and systemic dependency, measured with the HHI (nids-dns-ecosystem) |
Be specific. “Internet topology” is not an answer; “router-level links inferred from traceroute, and when their inferred geolocation can be trusted” is.
Background
Provide the context a student needs before the new material makes sense: slides, webpages, papers, or links to other NIDS assignments that introduce prerequisite concepts. Frame it around the material being introduced rather than as general reading.
What the Assignment Assumes
Anything not covered by a prerequisite assignment is new material, and this assignment has to teach it. That single rule decides most of what the repository contains.
List the prerequisite assignments explicitly, and say what each one supplies — not just that it exists. The practical consequence for tools: if a prerequisite already taught the tool, cite the prerequisite. If the tool is new here, the assignment ships a guide for it. If a prerequisite covers it only partly, ship a guide covering just the difference.
Resources: Known and New
Full list of all the resources that will be used.
-
Resources Known
List the datasets, tools, and libraries the student is expected to understand before beginning this assignment. This list should be organized around the prerequisite assignments which introduce this information. -
Resources New
List the datasets, tools, and libraries that are introduced for the first time in this assignment. For each new resource:-
Provide enough detail for students to understand what the resource is and why it is used.
-
Link, to an existing, or create a new, catalog.caida.org recipe for scripts and deeper documentation. (optional)
Catalog Recipes are technical methodologies used to derive a particular conclusion or a particular dataset, which can be used for further synthesis and analysis. These will include example code and more details than present in the assignment.
-
How the Tasks Force Engagement
Naming the new material is not enough — the tasks have to make the student actually use it. The test: a student should not be able to finish a task by falling back on what they already knew.
Two published assignments show what this looks like:
- nids-iyp’s three tasks deliberately re-do analyses the student already completed in earlier assignments. Because the answers are already familiar, the only thing left to learn is expressing them as a single graph traversal instead of a hand-written join across separate datasets.
- nids-ucsdnt-expanse makes the student port an interactive prototype into a Slurm batch array — not as an exercise for its own sake, but because that is the only way to cover the time period the analysis needs.
Analysis
Sequence the tasks so each piece of new material is exercised on its own before it is combined with anything else:
- For each new resource, begin with a self-contained introduction — a small task that uses only that resource, so a mistake is easy to localize.
- Then combine the known and new resources in a task that cannot be completed with either alone.
What the Student Produces
Name the deliverables explicitly, and mark each one with ⬅ in the README’s directory
tree so there is no ambiguity about what gets submitted.
Most assignments produce a single notebook named for the repository — nids-itdk.ipynb
in nids-itdk. Some need more:
nids-telescope-traffic ships two
notebooks, and nids-ucsdnt-expanse
ships two notebooks plus a batch script and a Slurm submission file. Ship more than one
only when the work genuinely divides — a prototype and a full-period analysis are
different deliverables; splitting one analysis across two files is not.
Example: nids-iyp
Drawn from nids-iyp, the assignment that most clearly introduces both a dataset and a tool.
- Introduces:
- Dataset — the Internet Yellow Pages (IYP), which loads over 80 Internet-measurement datasets into a single Neo4j graph where an AS, a BGP prefix, a hostname, and an IXP are all typed nodes
- Tool — Cypher, Neo4j’s pattern-matching query language
- Idea — provenance: because sources genuinely disagree, IYP stores each source’s claim as its own relationship rather than overwriting a single property
- Assumes: ASN, BGP, DNS, and RPKI concepts, each from a named prerequisite assignment. Cypher is not covered by any of them, so the assignment ships
Cypher.mdand puts it in the Overview steps before the tasks. - How the tasks force engagement: the three tasks — an AS’s ecosystem, bridging announced address space to hosted domain names, and RPKI authorizations versus observed BGP origins — are all analyses the student has done before by hand. Repeating them against a graph is what teaches the traversal.
- Produces:
nids-iyp.ipynb⬅ — multi-hop Cypher queries, plus a written reading of what it means when two independent sources disagree about the same fact.
Where Each Part Lives
The sections above are a way of thinking about the assignment, not a list of files. They map onto the repository like this:
| Part | Where it lives |
|---|---|
| What it introduces | The README’s ## Learning Objectives, elaborated in Introduction.md |
| Background | Introduction.md — its reading list and concept sections |
| What it assumes | Introduction.md’s ### Prerequisite NIDS Assignments, with a note on what each supplies |
| The data | Datasets.md — what each dataset is, how to reach it, and its schema |
| The tools | A tool guide named for the tool (SQL.md, Cypher.md, Spark.md, Dpkt.md), required for any tool a prerequisite doesn’t already cover |
| The tasks | Tasks.md (the checklist), one Task-N-<slug>.md guide per task, and the notebook |
| What’s produced | The ⬅ deliverables; the private repository holds the worked, executed reference version |
Once you can fill in that table for your assignment, go back to Step 1 and create the repositories. The NIDS Assignment Style Guide specifies the format of each of these files, along with the breadcrumb navigation, banner, and notebook cell conventions they all share.