<epigraph>
  <attribution>J. Gustav White</attribution>
  <simpara
    >One can search the brain with a microscope and not find the mind,
    and can search the stars with a telescope and not find God.</simpara>
</epigraph>

<simpara
  >This is the platform independent part of &yref.scanners;.</simpara>
<simpara
  >After finding an exploitable peculiarity you need to verify
  its existence in a typical population of target executables.
  And then some peculiarities can be used only once. For example
  filling the segment gap on i386 removes the gap. This makes the
  issue kind of dual-use technology.
</simpara>
<simpara
  >In the beginning scanners were written in
  <application>perl</application>.
  <xref linkend="scan.entry.point"/> is the last remnant of that age.
  Unfortunately typical 64-bit platforms provide a
  <application>perl</application> with only 32-bit integers.
  The classic tool for calculations with large numbers is
  <application>bc</application>, a front-end to
  <application>dc</application>.
  But then classic <application>bc</application> on Solaris
  has only limited means of formatting output. I failed to
  write a <application>perl</application> script that writes
  a <application>bc</application> script that writes the output.
  Alternatively a bidirectional pipe opened by
  <citerefentry>
    <refentrytitle>IPC::Open2</refentrytitle>
    <manvolnum>3pm</manvolnum>
  </citerefentry> as described in
  <citerefentry>
    <refentrytitle>perlipc</refentrytitle>
    <manvolnum>1</manvolnum>
  </citerefentry> could be used to do calculations only. I chose a
  straight implementation in C instead, using the framework in
  <xref linkend="one.step.closer"/>. 
</simpara>

<sect2>
  <title>Finding executables</title>

  <simpara
    >The first thing we need is a list of target executables.
    The <quote>big</quote> set consists of system files in the
    usual places like <filename>/bin</filename>. The
    <quote>small</quote> set comprises all infected targets created
    by the examples in this document. These two groups are further
    divided into statically or dynamically linked.
  </simpara>
  <simpara
    >At the core of the following script is a combination of
    <application>file</application> and <application>sed</application>.
    The only special argument is the postfix required of target
    file names. A quoted empty string (<literal>""</literal>) accepts
    all files in target directories. The other typical value is
    <literal>"_infected"</literal>. This postfix is used by all
    examples in this document.
  </simpara>
  <simpara
    ><application>GNU find</application> and <application>GNU
    xargs</application> provide a nice extension,
    <option>-print0</option> and <option>-0</option>, respectively.
    They are also available on FreeBSD. Another interesting option
    of <application>GNU xargs</application>, <option>-r</option>, has
    not made it to FreeBSD, though. Obviously we can't use any of this.
  </simpara>
  <simpara
    >In this script <application>sed</application> does not write
    all output to <literal>stdout</literal>. Command <quote>w</quote>
    is used to write lines matching different patterns to different
    files. Since the file name is an argument to
    <filename>find_exec.sh</filename> the <application>sed</application>
    script has to be created inline. However, the syntax rules
    of <application>sed</application> require consecutive commands
    of a block to be separated by a line feed. And in a shell script
    single quotes are required to preserve line feeds in command lines.
    All together this results in a strange sequence of different
    quotes. The <literal>TEVWH_</literal> variables are shown
    in &yref.packages;. Output and a sample from
    <application>file</application> are at &yref.scanners;.
  </simpara>

  <formalpara>
    <title>Source: src/scanner/find_exec.sh</title>
    <para>
      <programlisting><inlinemediaobject><imageobject><imagedata
        format="linespecific"
        fileref="../src/scanner/find_exec.sh"
      /></imageobject></inlinemediaobject></programlisting
    ></para>
  </formalpara>

</sect2>
<sect2 id="driver.scripts">
  <title>Driver scripts</title>

  <simpara
    >The first kind of scanner parses the output of
    <application>objdump</application>. Since this output contains the
    file name of targets we can call <application>objdump</application>
    with multiple arguments (through <application>xargs</application>).
    <xref linkend="scan.entry.point"/> is now the only species of this
    kind.
  </simpara>

  <formalpara>
    <title>Source: src/scanner/objdump.sh</title>
    <para>
      <programlisting><inlinemediaobject><imageobject><imagedata
        format="linespecific"
        fileref="../src/scanner/objdump.sh"
      /></imageobject></inlinemediaobject></programlisting
    ></para>
  </formalpara>

  <simpara
    >The second kind of scanners reads a plain list of target file
    names from <literal>stdin</literal>.
  </simpara>

  <formalpara>
    <title>Source: src/scanner/plain.sh</title>
    <para>
      <programlisting><inlinemediaobject><imageobject><imagedata
        format="linespecific"
        fileref="../src/scanner/plain.sh"
      /></imageobject></inlinemediaobject></programlisting
    ></para>
  </formalpara>


</sect2>
<sect2 id="scan.entry.point" xreflabel="Scan entry point">
  <title>Scan entry point</title>

  <simpara
    >This script reads the output of <application>objdump</application>.
    For each file the start of section <literal>.text</literal>
    should equal the entry point. This can be implemented through a
    simple string comparison, i.e. by checking hexadecimal digits one
    by one. See &yref.sections; for an illustrative description
    based on a dumped <acronym>ELF</acronym> header.
  </simpara>

  <formalpara>
    <title>Source: src/scanner/entry_point/objdump.pl</title>
    <para>
      <programlisting><inlinemediaobject><imageobject><imagedata
        format="linespecific"
        fileref="../src/scanner/entry_point/objdump.pl"
      /></imageobject></inlinemediaobject></programlisting
    ></para>
  </formalpara>

</sect2>
<sect2 id="scan.segments" xreflabel="Scan segments">
  <title>Scan segments</title>

  <simplesect id="target.action.2" xreflabel="target_action #2">
    <title>target_action #2</title>

    <simpara
      >This is a scanner to verify the existence of the gap used in
      <xref linkend="segment.padding"/>. The output at &yref.scanners;
      is ambiguous. We can positively tell whether the gap exists or
      not. But we cannot say whether the gap never existed or is
      indeed occupied by an infection.
      On platforms other than i386 alignment is larger than page size.
      It is possible that a small infection taking just one page
      affects a single target more than once and still leaves a gap
      larger than the segment alignment. These cases go undetected
      by this script.
    </simpara>
    <simpara
      >Anyway, <literal>det_page</literal> is the number of files
      detected to have a gap smaller equal one page (no further infection
      possible). <literal>det_align</literal> is the number of files
      where the gap is smaller than segment alignment (probably infected).
      Obviously these criteria overlap.
    </simpara>

    <formalpara>
      <title>Source: src/scanner/segment/action.inc</title>
      <para>
	<programlisting><inlinemediaobject><imageobject><imagedata
	  format="linespecific"
	  fileref="../src/scanner/segment/action.inc"
	/></imageobject></inlinemediaobject></programlisting>
      </para>
    </formalpara>

  </simplesect>
  <simplesect id="print.summary.2" xreflabel="print_summary #2">
    <title>print_summary #2 (segments)</title>

    <simpara>Outputs the statistics of
      <xref linkend="target.action.2"/>.</simpara>

    <formalpara>
      <title>Source: src/scanner/segment/print_summary.inc</title>
      <para>
	<programlisting><inlinemediaobject><imageobject><imagedata
	  format="linespecific"
	  fileref="../src/scanner/segment/print_summary.inc"
	/></imageobject></inlinemediaobject></programlisting>
      </para>
    </formalpara>

  </simplesect>
</sect2>
<sect2 id="scan.filesize" xreflabel="Scan file size">
  <title>Scan file size</title>

  <simplesect id="target.action.3" xreflabel="target_action #3">
    <title>target_action #3</title>

    <formalpara>
      <title>Source: src/scanner/filesize/action.inc</title>
      <para>
	<programlisting><inlinemediaobject><imageobject><imagedata
	  format="linespecific"
	  fileref="../src/scanner/filesize/action.inc"
	/></imageobject></inlinemediaobject></programlisting>
      </para>
    </formalpara>

  </simplesect>
  <simplesect id="print.summary.3" xreflabel="print_summary #3">
    <title>print_summary #3 (file size)</title>

    <simpara>Outputs the statistics of
      <xref linkend="target.action.3"/>.</simpara>

    <formalpara>
      <title>Source: src/scanner/filesize/print_summary.inc</title>
      <para>
	<programlisting><inlinemediaobject><imageobject><imagedata
	  format="linespecific"
	  fileref="../src/scanner/filesize/print_summary.inc"
	/></imageobject></inlinemediaobject></programlisting>
      </para>
    </formalpara>

  </simplesect>
</sect2>
